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PREFACE 



0.1 MANUAL OBJECTIVES AND READER ASSUMPTIONS 

The goal of this manual is to provide all the information necessary to 
successfully prepare a conventional I/O driver for RSX-llM and 
subsequently incorporate it into an operational user-tailored system. 
A "conventional" driver is best explained by example. Disks and unit 
record devices are considered conventional; the LPS-11, UDC-11, and 
TM11 are considered non-conventional. Complexity of device servicing 
requirements sets the dividing line, a line not easily established in 
go, no-go terms. 

The manual assumes the reader fully understands the device for which 
he is writing a driver, and has complete familiarity with the PDP-11 
computer, its peripheral devices, and the software supplied with an 
RSX-llM system. Complete familiarity implies an in-depth exposure to 
the following RSX-llM manuals (see section 0.3 below): 

1. System Generation Manual 

2. I/O Drivers Reference Manual 

3. Executive Reference Manual 

4. Utilities Procedures Manual 

5. I/O Operations Reference Manual 

Although this manual is organized tutorially, our reader class 
assumptions require a system programmer level of expertise; thus, the 
manual will not contain definitions of data processing terms and 
concepts familiar to senior level professionals. 

As adjuncts to this manual, the reader is advised to study existing 
I/O drivers. The RF-11 disk driver is a good example of an NPR device 
and the TA-11 (cassette) is illustrative of a programmed I/O device. 
In addition, a perusal of the source code contained in the files 
IOSUB, SYSXT, DRQIO, BFCTL, and DRDSP (stored under UIC [11,10] on the 
source disk) should prove beneficial. 
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0.2 STRUCTURE OF THE DOCUMENT 

This document cascades from chapter to chapter toward increasing 
levels of implementation detail. 

Chapter 1 is a functional description of the RSX-11M device level I/O 
system, covering both data structure and code requirements. 

Chapter 2 details how a user-written driver is incorporated into the 
system. 

Together, Chapters 1 and 2 provide a complete understanding of the 
requirements that must be met in creating a system which contains a 
user-written driver. 

Chapter 3 provides programming level details on I/O data structures. 

Chapter 4 covers all the I/O-related Executive services. 

Chapter 5 is an example of a user-written driver. 

Appendix A describes the Address Doubleword. 

Appendix B lists system macros which supply symbolic offsets for 
system data structures. 



0.3 ASSOCIATED DOCUMENTS 

Other manuals closely allied to the purposes of this document are 
described briefly in the RSX-11M/RSX-11S Documentation Directory , 
Order No. DEC-11-OMUGA-B-D. The Documentation Directory defines the 
intended readership of each manual in the RSX-11M/RSX-11S set and 
provides a brief synopsis of each manual's contents. 
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CHAPTER 1 
THE RSX-11M I/O SYSTEM - PHILOSOPHY AND STRUCTURE 



1.1 I/O PHILOSOPHY 

Memory constraints and RSX-11D compatibility requirements dominated 
the design philosophy and strategy used in creating RSX-11M. To meet 
its performance and space goals, the RSX-11M I/O system attempts to 
centralize common functions, thus eliminating the inclusion of 
repetitive code in each and every driver in the system. To achieve 
this, a substantial effort has been expended in the design of 
RSX-llM's data structures. These structures are used to drive the 
centralized routines; the effect is to substantially reduce the size 
of individual I/O drivers. The table structures, of course, require 
space and must be considered with the total size of the I/O system. 
Nevertheless, the size reduction effected by the centralization of 
functions, combined with table-driven design, has enabled RSX-llM to 
meet its original memory and performance goals. 

In a DEC-released system, DEC-supported drivers are included into the 
user-tailored system via system generation queries. User-written 
drivers require the user to create object files for I/O data 
structures and driver code. These object files are built and 
incorporated during the generation of the user-tailored system. 



1.2 STRUCTURE 
This section: 

1. Places an I/O driver in the context of the overall RSX-llM 
I/O system; 

2. Establishes the responsibilities of an I/O driver, and 

3. Functionally describes the driver's interface to the 
Executive subroutines and the I/O data structures. 



1.2.1 I/O Hierarchy 

The RSX-llM I/O system is structured as a loose hierarchy. The term 
"loose" simply indicates that the hierarchy can be entered at any of 
its levels; this characteristic is contrasted to "tight" hierarchies 
which permit entry only from the top. Tight hierarchies exist 
principally for security and protection, but are costly in their 
consumption of equipment resources. Figure 1-1 shows the loose I/O 
system hierarchy. 
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Figure 1-1 
I/O Control Flow 



1.2.1.1 FCS - At the top of the hierarchy is File Control Services 
(FCS) which provides device-independent access to devices included in 
a given system configuration. The user task has two levels with which 
to interface with FCS; Get/Put and Read/Write. Get/Put facilitates 
the movement of data records, whereas Read/Write provides a more basic 
level of access affording more direct control over data movement 
between a task and peripheral devices. 

The discussion of FCS has been purposely terse because its existence 
is completely transparent to the driver and rarely concerns the writer 
of a conventional driver. FCS will accept a user request, interpret 
it, and perform all operations necessary to carry out the user 
request . 



1-2 



THE RSX-11M I/O SYSTEM - PHILOSOPHY AND STRUCTURE 

1.2.1.2 QIO - The QIO directive is the lowest level of task I/O. Any 
task may issue a QIO directive. The QIO directive allows more direct 
control over devices which are connected to a system and for which an 
I/O driver exists. The QIO directive forces all I/O requests from 
user task's to go through the Executive. The Executive prevents tasks 
from destructively interfering with each other and with the Executive. 



1.2.1.3 Executive I/O Processing - The processing of I/O requests by 
the Executive I/O system is accomplished via: 

1. File Control Primitives (FCP) , and 

2. A collection of Executive components consisting of: 

a PlTn r\ i r an +- i uo nrAfOQsinri' 

b. I/O-related subroutines, and 

c. The I/O drivers. 

FCP is a privileged task; it is responsible for maintaining the 
structure and integrity of data stored on file-structured volumes. It 
maps virtual block numbers to logical block numbers, extends files, 
and makes volume protection checks. No direct connection exists 
between FCP and a driver. 

Logical blocks are 256 words in length; it is the responsibility of 
the driver to convert a logical block number into a physical address 
on a file-structured device. 

Within the system, FCP exists as a privileged task, possessing all the 
attributes of privileged tasks. FCP requires a partition in which to 
execute. Drivers, on the other hand, are specialized, 
permanently-resident system processes, not tasks. 

The I/O services provided by the Executive consist of QIO directive 
processing, and a collection of subroutines used by drivers to obtain 
I/O requests, facilitate interrupt handling, and return status upon 

/-. r\m r\^ ^ 4- i s\ r, r\ -F =rl T /Pi r aQnac +• / 3 <"-■■£ rj =s T^ COntrOl Of the dCV iC 6 iS 

performed by the driver). These subroutines will be examined in 
considerable detail later. Executive subroutine services and QIO 
directive processing are shown as distinct components but are, in 
fact, both parts of the Executive. These are the routines which 
centralize common driver functions, thus eliminating duplicate code 
sequences among drivers. 

The description of the I/O hierarchy and interrelationships is now 
sufficiently complete to allow a more direct consideration of the role 
fulfilled by an I/O driver in an RSX-11M system. 
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1.2.2 Role of I/O Driver in RSX-11M 
Every driver has five entry points: 

1. Device interrupt*; 

2. I/O initiator; 

3. Device timeout; 

4. Cancel I/O, and 

5. Power failure. 

The first entry point is entered via a hardware interrupt; the last 
four are entered by calls from the Executive. These entry points are 
descriptive enough in and of themselves to provide direct insight into 
the responsibilities of a driver; the functional details follow. 



1.2.2.1 Device Interrupt - Control is passed to this entry point when 
a device previously initiated by the driver has completed an I/O 
operation and has caused an interrupt in the central processor. The 
connection to the driver in this instance is direct; the Executive is 
not involved. 



1.2.2.2 I/O Initiator - This entry point is called by the Executive 
to inform the driver that work for it is waiting to be done. In 
effect, this is a wakeup signal for the driver. 



1.2.2.3 Device Timeout - When a driver initiates an I/O operation, it 
establishes a timeout count. If the function does not complete within 
the specified time interval, the Executive will note the time lapse 
and call the driver at this entry point. 



1.2.2.4 Cancel I/O - A number of circumstances arise within the 
system which require that a driver terminate an in-progress I/O 
operation. When this becomes necessary, a task so informs the 
Executive which then relays the request to the driver by calling it at 
the cancel I/O entry point. 



1.2.2.5 Power Failure - Two conditions can initiate a call to the 
driver when power is restored following a power failure. First, the 
power failure entry point is automatically called by the Executive any 
time the controller is busy. Secondly, a driver has the option to be 
called regardless of the existence of an outstanding I/O operation at 
the time the power is restored. If power fails, and the conditions 



* A device may trigger more than one distinct interrupt entry. For 
example, a full duplex device would have two. 
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exist for power failure code initiation, the Executive will so inform 
the driver by calling it at the power failure entry point when power 
is restored. Frequently, a driver's response to a power failure or an 
I/O failure is identical to that when its device times out; in such a 
case, the power failure entry point may simply be a return, since 
recovery will eventually be effected via the timeout entry point. 

Also, when the system is bootstrapped, a power failure interrupt is 
simulated. This simulation gives drivers the opportunity to carry out 
any pre-operational initialization deemed appropriate. 



1.2.2.6 Summary - Role of an I/O Driver - Functionally, the driver in 
RSX-11M has responsibility for: 



2. Initiating I/O operations; 

3. Cancelling in-progress I/O operations, and 

4. Performing device-related functions upon the occurrence of 
timeout or power failure. 

A driver exists as an integral part of the Executive; it can call and 
be called b v the Executive. The driver initiates device I ^^ 
operations directly and receives device interrupts directly. All 
other entry points are entered via Executive calls. A driver never 
receives a QIO request directly, and has no direct interaction with 
FCP. 

At this point, a functional description of the role of an I/O driver 
in RSX-11M has been presented. In the next three sections, the 

Data structures, 

Fyopiif l'uo go r \7 i r> o a arirl 

Programming conventions and protocol 

related to I/O drivers will be discussed. The chapter closes with a 
section discussing the flow of an I/O request, from the issuance of a 
QIO directive to the delivery of the requested data to the task. Data 
structure interrelationships are also covered. 



1.3 DATA STRUCTURES 

There are seven data structures with which an I/O driver interacts: 

1. Device Control Blocks (DCB's); 

2. Unit Control Blocks (UCB's); 

3. Status Control Blocks (SCB's); 

4. The I/C Packet; 

5. The I/O Queue; 
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6. The Fork List, and 

7. Device Interrupt Vectors. 

The first four are most important to the driver, since it is via these 

data structures that all I/O operations are effected. They also serve 

as communication and coordination vehicles between the Executive and 
individual drivers. 

The I/O Queue and the Fork List are actually Executive data 
structures, but to properly understand the complete interaction of an 
I/O driver with the Executive, their role in the system will also be 
described. The I/O Queue is a list of I/O Packets which are built by 
the QIO directive, principally from information in the caller's 
Directive Parameter Block (DPB) . 

Entry to a driver following a device interrupt is direct via the 
appropriate hardware device interrupt vector. Since the driver writer 
is responsible for properly establishing this vector, it is included 
in the data structures associated with a driver. 



1.3.1 The Device Control Block (DCB) 

At least one DCB exists for each type of device appearing in a system 
(device type should not be equated with a device-unit). The function 
of the DCB is to describe the static characteristics (rather than 
execution-time information) of both the device controller and the 
units attached to the controller. All the DCB ' s in a system form a 
forward-linked list, with the last DCB having a link of zero. Most of 
the data in the DCB is established in the assembly source for the 
driver data structure. The DCB is used by the QIO directive 
processing code in the Executive and not by the driver. 



1.3.2 The Unit Control Block (UCB) 

One UCB exists for each device-unit attached to a system. Much of the 
information in the UCB is static, though a few dynamic parameters 
exist. For example, the redirect pointer, which reflects the results 
of an MCR Redirect command, is updated dynamically. As with the DCB, 
most of the UCB is established in the assembly source; however, its 
contents are used and modified by both the Executive and the driver, 
though modification of a given datum is done exclusively by either the 
Executive or driver, not both. 



1.3.3 The Status Control Block (SCB) 



One SCB exists for each device controller in the system. This is true 
even if the controller handles more than one device-unit (like the 
RKll Controller) . Line multiplexers such as the DH11 and DJ11 are 
considered to have a controller per line since all lines may transfer 
in parallel. Most of the information in the SCB is dynamic. The SCB 
is used by both the Executive and the driver. 
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1.3.3.1 Interrelation of the I/O Control Blocks - Without explicit 
details on the contents of the DCB, UCB, and SCB, their relationships 
are difficult to correlate. This section is intended to represent 

+-V"io i r inforrol afirmohin tj n 4- Vi r» 1 1 4- on 4-o r 1 nn i r\ t-r\ 4-Vi£> ^et-s i 1 »<^ ^««*-^«»i.« «.« 

w»»x «. » -...^.^.^^v.-.w.w^.-^..^^.^.^ A...W4VVIV. ._ , j •„-„ t .t ! i>-J ilil,^ UIIC UCLOI1J.CU ^uiiuciii.s \j 1. 

the control blocks, leaving such a discussion to be pursued in Chapter 
3. 

Figure 1-2 shows the data structure that would result for three LA30 
DECwriters interfaced via DL11 controllers. The structure requires 
one DCB, three UCB's, and three SCB's, since the activity on all three 
units can proceed in parallel. 

In Figure 1-3, the internal data structure for an RK11 disk controller 
with three units attached is depicted. Note that only one SCB exists 
because only one of the three units may be active at any given time. 







Figure 1-2 
DL11 Disk I/O Data Structure 
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Figure 1-3 
EK11 Disk I/O Data Structure 



Taken together, Figures 1-2 and 1-3 illustrate the strategy underlying 
the existence of three basic I/O control blocks. There need be only 
one DCB per device type. The SCB, depending on the degree of 
parallelism that is desired or possible, can exist for each 
device-unit, or only once for controllers servicing multiple 
device-units . 

As will be seen later, this data structure has the effect of providing 
considerable flexibility in configuring I/O devices, and, due to the 
information density in the structures themselves, substantially 
reduces the code requirements of the associated drivers. 



1.3.4 The I/O Packet 

An I/O Packet contains information extracted from the QIO DPB and 
other information needed to successfully initiate and terminate I/O 
reauests . 



1.3.5 The I/O Queue 

Each time an I/O request is made, the Executive is entered, and, if a 
series of validity checks proves successful, the Executive will 
generate a data structure called an I/O Packet. The Executive will 
then insert the packet into a device specific, priority-ordered list 
of packets called the I/O Queue. Each I/O Queue's listhead is located 
in the SCB to which the I/O requests apply. 

When a device driver needs work, it requests the Executive to de-queue 
the next I/O Packet and deliver it to the requesting driver. The 
driver never directly manipulates the I/O Queue. 
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1,3=6 The Fork List 

All drivers in RSX-11M can easily be written as multi-controller 
drivers; all drivers may run in parallel with other drivers and with 
themselves. When independent processes may execute in parallel, a 
method for synchronizing their access to common data bases is 
essential. At the Executive level in RSX-11M, a process may 
synchronize its access to a data base by requesting the Executive to 
transform it into a fork process. Such an operation creates a 
specialized context for the process and places it into a list called 
the Fork List. Processes in the Fork List are granted FIFO access to 
common data bases. Once granted access to the data base, the process 
is guaranteed control of the data base until it relinquishes it by 
exiting. Not until the process exits will the next process in the 
Fork List be granted data base access. Thus, it is via the fork 
mechanism and the associated Fork List that access to shared system 
data bases is synchronized. Essentially, of the two basic techniques 
available for data base access synchronization: 

1. Interrupt lockout, and 

2. Access queuing, 
RSX-11M has chosen the latter. 



1.3.7 The Device Interrupt Vector 

The device interrupt vector is initialized when defining data 

structures, and not dynamically. This makes the driver code 

independent of device register address assignments and the actual 

location of the interrupt vector. 

The driver data structure must include a storage assignment and 
initialization for the interrupt vector with the priority set to 7. 
See lines 81 thru 85 in section 5.2.1 (section 5.2.1 contains the 
source code for the data structure of a sample driver). 



1.4 EXECUTIVE SERVICES 



The I/O-dr iver-related services provided by the Executive can be 
categorized as pre- and post-driver initiation. The pre-initiation 
services are those performed by the Executive during its processing of 
a CIO directive; these services are not available as Executive calls. 
The goal of this processing is to extract from the driver all I/O 
support functions not directly related to the actual issuance of a 
function request to a device. If the outcome does not' result in the 
cueueing of an I/O Packet to a driver, the driver is unaware that a 
CTO directive was ever issued. As will be shown shortly, many QIO 
directives do not result in the initiation of an I/O operation. 
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1.4.1 Pre-Driver Initiation Processing 

CIO directive processing performs the following pre-driver initiation 

services : 

1. Checks if the supplied logical unit number (LUN) is legal. 
If not, the directive is rejected. 

2. If the LUN is valid, check if a valid UCB pointer exists in 
the Logical Unit Table (LUT) for the specified LUN. This 
test determines if the LUN is assigned. If the test fails, 
the directive is rejected. 

3. If steps 1 and 2 are successful, the Executive traces down 
the redirect chain to locate the correct UCB to which the I/O 
operation will actually be directed. 

4. Checks the event flag number (EFN) and the address of the I/O 
Status Elock (IOSB). If either is illegal, the directive is 
rejected. Immediately following validation, the subject 
event flag is reset, and the IOSB is cleared. 

5. Obtains 18-words of dynamic storage and builds the 
device- independent portion of an I/O Packet. 

If steps 1 thru 5 succeed, the directive status is set to +1. 

Note that directive rejections in any of the above steps are 
completely transparent to the driver. 

6. Checks the validity of the function being requested and, if 
appropriate, checks the buffer address, byte count, and 
alignment requirements for the specified device. 

If any of these checks fails, the I/O Finish routine ($IOFIN) 
is called. $IOFIN sets status and clears the QIO request 
from the system. 

7. If the requested function does not require a call to the 
driver, appropriate actions are handled by the Executive and 
$IOFIN is called. 



s 



If all I/O Packet checks are positive, the I/O Packet i_ 
placed in the driver queue according to the priority of the 
requesting task. 



1.4.2 Post-Driver Initiation Services 

Once a driver is given control following an I/O interrupt or by the 
Executive itself, a number of Executive services are available to I/O 
drivers. These services are discussed in detail in Chapter 4. 

There are, however, four Executive services that merit special 
emphasis, since they are used by virtually every driver in the system: 

1. Interrupt Save ($INTSV); 

2. Get Packet ($GTPKT) ; 
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3. Create Fork Process ($FORK) , and 

4. I/O Done ($IODON) . 



1.4.2.1 Interrupt Save ($INTSV) - Interrupts from a device are 
fielded directly by the driver. Immediately following the interrupt, 
the driver is operating at hardware priority level 7 and is, 
therefore, non-interruptible. If the driver needs a lengthy 
processing cycle (greater than lOOus) to process the interrupt or 
requires registers, it should call $INTSV; this has the effect of 
stacking external interrupts, altering the hardware priority, and 
providing the calling routine with two free registers to use in 
processing the interrupt. More will be said about $INTSV in section 
1.5. 



1.4.2.2 Get Packet ($GTPKT) - The Executive, after it has queued an 
I/O Packet, calls the appropriate driver at its I/O-initiator entry 
point. The driver then immediately calls the Executive routine $GTPKT 
to obtain work. When work is available, $GTPKT delivers to the driver 
the highest priority, executable I/O Packet in the driver's I/O queue, 
and sets the SCB status to busy. If the driver's I/O Queue is empty, 
$GTPKT returns a no-work indication. 

If the SCB related to the device is already busy, $GTPKT so informs 
the driver, in which case the driver immediately returns control to 
its caller . 

To the driver writer, note that no distinction exists between no-work 
and SCB busy, since, in either case, an I/O operation cannot be 
initiated . 



1,4=2=3 Create Fork Process ($FORK) - Synchronization of access to 
shared data bases is accomplished via a fork process. When a driver 
needs to access a shared data base, it must do so as a fork process; 

J-l J - 1 4-~ „ ~ -P,^ ,, I, ^-^^^^^ U,t ^ -n 1 1 i ~ /-r CUHlTiV 



1.4.2.4 I/O Done ($IQDON) - At the completion of an I/O request, a 
number of centralized checks and additional functions are performed: 

Store status if an IOSB address was specified. 

Set an event flag, if one was requested. 

Determine if a checkpoint request can now be honored. 

Determine if an AST should be queued. 

$IODON also declares a significant event, resets the SCB and device 
unit status to idle, and releases the dynamic storage used by the 
completed I/O operation. 
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1.5 PROGRAMMING STANDARDS 

RSX-llM I/O drivers are integral components of the RSX-11M Executive. 
As such, they must follow the same conventions and protocol as the 
Executive itself, if they are to avoid complete disruption of system 
service. This manual has been written to enable programmers to 
incorporate I/O drivers into their systems. Failure to observe the 
internal conventions and protocol will result in poor service and 
reductions in system efficiency. 



1.5.1 Process-Like Characteristics of a Driver 

A driver is an asynchronous Executive process. As a process, it 
possesses its own context, allows or disallows interrupts, and 
synchronizes functions within itself (all drivers can be parallel, 
multi-unit, multi-controller) and with other Executive processes 
executing in parallel. 

RSX-llM drivers are small; their small size is made possible by a 
comprehensive complement of centralized services available by calls to 
the Executive and b w the availabil it v of an information— dense - hiohl v 
formalized I/O data structure. 



1.5.2 Programming Conventions 

The programming conventions used by RSX-llM system components are 
identical to those described in Appendix E of the RSX-11 MACRO-11 
Reference Manual. Users preparing I/O drivers for incorporation into 
an RSX-llM system are strongly urged to adhere to these conventions. 



1.5.3 Programming Protocol 

Since an I/O driver accepts interrupts directly from the devices it 
controls, the central Executive relies on the driver to follow strict 
programming protocol so that system performance is not degraded. 
Furthermore, the protocol ensures that the driver properly distributes 
shared resources according to user-specified priorities. 

When a device interrupts, an I/O driver is entered directly, usually 
calling $INTSV for common save and state switching services. (Two 
states, user and system, exist in RSX-llM; the conventions discussed 
in this manual generally refer to processes running from the system 
state, since drivers operate entirely in system state.) At the 
completion of the services provided by $INTSV, the interrupt routine 
is again given control to complete the interrupt service. The exit 
routine $INTXT restores the state prior to switching to the system 
state, controls the un-nesting of interrupts, and makes checks on the 
state of the system (for example, it checks if it is necessary to 
switch tasks). The Fork Processor linearizes access to shared system 
data bases. The details of all these routines will be covered in 
Chapter 4. 

The interrupt vectors in lower memory contain a Program Counter (PC) 
unique to each interrupting source and a Processor Status Word (PS) 
set with a priority of 7, it is a system software convention to use 
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the low-order four bits of the PS word to encode the controller number 
for muLticontroller drivers. When a device interrupt occurs, the 
hardware pushes the current PS and PC onto the current stack and loads 
the new PC and PS (set at PR7 with the controller number in the 
condition code bits) from the appropriate interrupt vector (the driver 
data base source must set up the interrupt vector) . The driver then 
starts executing with interrupts locked out. A driver itself may be 
executing at one of three levels of interrupt sensitivity: 

1. At priority 7 with interrupts locked out; 

2. At the priority of the interrupting source; thus, interrupt 
levels greater than the priority of the interrupting source 
are permitted, or 

3. At fork level which is at priority 0. 



1.5.3.1 Processing at Priority 7 with Interrupts Locked Out - By 
internal convention, processing at this level (interrupt processing 
routine level 1) is limited to lOOus. If processing can be completed 
in this time, then the driver simply dismisses the interrupt by 
executing an RTI instruction. The interrupt has been processed and 
dismissed with minimal overhead. 



1.5.3.2 Processing at the Priority of the Interrupting Source - If 
the driver requires additional processing time or the use of general 
purpose registers, it calls the routine $INTSV (Interrupt Save). The 
priority at which the caller is to run immediately follows the call to 
$INTSV. The driver should set this priority level to that of the 
interrupting source. 

$INTSV save uses the specified priority to set up the interrupt 
routine such that it is interruptible by priorities higher than that 
of the in ter r up t incj source and conditionally switches to system state 
if the processor is not already in system state. 

The saving of general registers R4 and R5 is done to free these 
registers for the driver. It is an internal programming convention 
that assumes the driver will not require more than two registers 
during interrupt processing. If it does, it must save and restore any 
additional registers it uses. Processing time following the return 
from $INTSV should not exceed 500us*. 

In actual practice, every driver in the system calls $INTSV on -every 
interrupt after executing perhaps or 1 instructions (such as saving 
the PS if more than one controller is being driven). This is due to 
two factors: 

1. It is difficult to service an interrupt without one or two 
registers . 



* The 500us period is a guideline. The shorter the period of time a 
realtime executive spends at an elevated priority level, the less 
responsive the system will be to devices of lower priority. This is 
especially important if the device being serviced is at the same or 
higher priority than a character-interrupt device such as the DU11, 
which is vulnerable to data loss due to interrupt lockout. 
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2. Most interrupt code may safely be executed at the priority of 
the interrupting source, which is, of course, desirable. 



1.5.3.3 Processing at Fork Level - A driver calls $FORK to meet the 
requirement to become fully interruptible (so as to conform to the 
500us time limit) or to access a shared system data base. $INTSV must 
be called prior to calling $FORK. 

By virtue of calling $FORK, the routine is now at processing level 3 
(interruptible) and its access to system data bases is strictly 
linear. The Fork List is a list of system routines waiting to 
complete their processing, in particular, waiting to access a shared 
system data base. At fork level, all registers are available to the 
process, and R4 and R5 retain the contents they had on entrance to 
$FORK. 



1.5.3.4 Programming Protocol Summary - Drivers are required to adhere 
to the following internal conventions when processing device 
inter r upts : 

1. Registers are not available for use unless $INTSV is called 
or the driver explicitly performs save and restore 
operations. If $INTSV is called, the use of any registers, 
except R4 and R5, requires that these registers be saved and 
restored . 

2. Non-interruptible processing must not exceed twenty 
instructions, and processing at the priority of the 
interrupting source must not exceed 500us. 

3. All modifications to system data bases must be done via a 
fork process. 



1.6 FLOW OF AN I/O REQUEST 

Following an I/O request through the system at the functional level 
(the level at which this chapter is directed) requires that limiting 
assumptions be made about the state of the system when the QIO 
directive is actually issued. The following assumptions apply: 

1. The system is up and ready to accept an I/O request. All 
required data structures for supporting devices attached to 
the system are intact. 

2. The only I/O request in the system will be the sample request 
under discussion. 

3. The example will progress without encountering any errors 
that would prematurely terminate its data transfer; thus, no 
error paths will be discussed. 
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The I/O flow proceeds as described below: 

1: [Task issues QIO directive] 

All Executive directives are called via EMT 377. The effect 
of the EMT is to cause the processor to stack the PS and PC 
and pass control to the Executive's directive processor. 

la. [First level validity checks] 

The QIO directive processor validates the LUN and UCB 
pointer. Invalid data results in directive rejection. 

lb. [Redirect algorithm] 

Since the UCB may have been dynamically redirected via an MCR 
Reuirect commanu, \^J.\j uirective processing traces mc 
redirect linkage until the target UCB is found. 

lc. [Additional validity checks] 

The EFN is validated as well as the address of the I/O Status 
Block (IOSB) . If valid, the event flag is reset and the I/O 
status block is cleared. 

2. [Obtain storage for and create an I/O Packet] 

QIO directive processing now acquires an 18-word block of 
dynamic storage for use as an I/O Packet. If the 18-words of 
storage are obtained, the directive is accepted. It inserts 
data items into the packet which are subsequently used by 
both the Executive and driver in fulfilling the I/O request. 
Most items originate in the requesting task's Directive 
Parameter Block ^DPB) . 

3. [Validate the function requested] 

The function is one of four possible types: 

a) Control; 

b) No-op; 

c) File, or 

d) Transfer. 

Control functions, with the exception of Attach/Detach, are 
queued to the driver. No-op functions do not result in data 
transfers and are performed by the Executive without calling 
the driver . 

A file function may require processing by the file system. 
More typically, the request is a read or write virtual 
function which is transformed into a read or write logical 
function without requiring file system intervention. When 
transformed into a read or write logical, it becomes a 
transfer function (read and write logical are, by definition, 
transfer functions) . 
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Transfer functions are address checked and queued to the 
proper driver. Then the driver is called at its initiator 
entry point. 

4. [Driver processing] 

4a. [Request work] 

To obtain work, the driver calls Get Packet ($GTPKT) . $GTPKT 
will either provide work, if it exists, or inform the driver 
that no work is available, or the SCB is busy; if no work 
exists, the driver returns to its caller. If work is 
available, $GTPKT will set the device controller and unit 
busy, dequeue an I/O request packet, and return to the 
driver . 

4b. [Issue I/O] 

From the available data structures, the driver initiates the 
required I/O operation and returns to its caller. A 
subsequent interrupt may inform the driver that the initiated 
function is complete, assuming the device is interrupt 
driven . 

5. [Interrupt processing] 

When a previously-issued I/O operation interrupts, the 
interrupt causes a direct entry into the driver, which 
processes it according to the programming protocol described 
earlier. According to the protocol, the driver may process 
the interrupt at priority 7, at the priority of the 
interrupting device, or at fork level. If the processing of 
the I/O request associated with the interrupt is still 
incomplete, the driver initiates further I/O on the device 
(4b). When the processing of an I/O request is complete, 
$IODON is called. 

6. [I/O Done processing] 

$IODON removes the device unit and controller busy status, 
queues an AST, if required, and determines if a checkpoint 
request pending for the issuing task can now be effected. 
The IOSB and event flag, if specified, are updated, and 
$IODON returns to the driver. The driver branches to its 
initiator entry point looking for more work (step 4a) . This 
procedure is followed until the driver finds the queue empty, 
whereupon, the driver returns to its caller. 

Eventually, the processor is granted to another ready-to-run 
process which will issue a QIO directive, starting the I/O 
flow anew. 
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1.7 DATA STRUCTURES AND THEIR INTERRELATIONSHIPS 
This section presents all the individual control blocks, their 

■t ,• „!,-,„«„ 3^/? ne>c yifhin M-io cusfpm. Thp fnllnwinq data structures 
comprise the complete set for I/O processing: 

1. Task Header; 

2. Window Block (WB) ; 

3. File Control Block (FCB) ; 

4. $DEVTB word, the Device Control Block (DCB) , and the Driver 
Dispatch Table (DDT); 

5. Unit Control Block (UCB) ; 

6. Status Control Block (SCB) , and 

7. Volume Control Block (VCB) . 

Figure 1-4, which will provide the structure for the following 
discussion, shows all the individual data structures and the important 
link fields within them. The numbers on the figure are keyed to the 
text to simplify the discussion and guide the reader through the data 
structures . 
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Figure 1-4 
I/O Data Structure 



The Task Header, one of two independent entries in the I/O 
data structure, is constructed during the task-build process. 
The entry of interest, the Logical Unit Table (LUT), is 
allocated by the Task Builder and filled in at task 
installation. The number of LUT entries is established by 
the UNITS= keyword option and places an upper limit on the 
number of device units a task may have active simultaneously. 
Each LUT entry contains a pointer to an associated UCB, and a 
pointer to a Window Block if a file is accessed. 

A Window Block (WB) exists for each active access to files on 
a mounted volume. Its function is to speed up the process of 
retrieving data items in the file; entries in a WB consist 
mainly of pointers to contiguous areas on the device where 
the file resides. 

Each uniquely-opened file on a mounted volume has an 
associated File Control Block (FCB). The file system uses 
the FCB to control access to the file. 

$DEVTB is a word located in system common (SYSCM) and is the 
other independent entry in the I/O data structure. $DEVTB 
points to a singly-linked, uni-directional list of Device 
Control Blocks (DCB's). Each device type in a system has an 
associated DCB. At least one DCB exists per device type. 
The DCB list is terminated by a zero in the link word. 

Linked to each DCB is a Driver Dispatch Table (DDT) . The DDT 
contains the addresses of the driver's four callable entry 
points . 
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A key data structure is the Unit Control Block (UCB) . All 
the UCB ' s associated with a DCB appear in consecutive memory 
locations. During internal processing of an I/O request, R5 
contains the address of the related UCB, and it is via 
pointers in the UCB that other control blocks in the data 
structure are accessed. In particular, the UCB contains 
pointers to the DCB, SCB, VCB, and to the UCB to which it may 
have been redirected. If a Redirect command has not been 
issued for the device-unit, the UCB redirect pointer points 
to the UCB itself. A driver services a fixed set of UCB's. 
When servicing a request for one of its UCB's, it is unaware 
of whether I/O was issued directly to the UCB or whether it 
was issued to a UCB redirected to its UCB. 

One Status Control Block (SCB) exists for each controller in 
a system. A unique SCB must exist for each controller/device 
unit capable of performing parallel I/O. The SCB contains 
the fork block storage required when a driver calls $FORK to 
transfer itself to the fork processing level. The I/O 
request queue listhead is also contained in the SCB. 

One Volume Control Block (VCB) exists for each MOUnted volume 
in a system. The VCB is used to maintain volume-dependent 
control information. It contains pointers to the File 
Control Block (FCB) and Window Block (WB) used to control 
access to the volume's index file. (The index file is a file 
of file headers.) The WB for the index file serves the same 
function as the WB for a user file. All unique FCB ' s for a 
volume form a linked list emanating from the index file FCB. 
This linkage aids in keeping file access time short. 
Further, since the window which contains the mapping pointers 
is variable in length, the user can increase file access 
speed by adding more access pointers (greater speed requires 
more main memory) to whatever extent his application 
requires. 



nafa Sfrnnhirpq Srnnmarv 



The writer of a conventional driver never manipulates the entire I/O 
data structure. In fact, he is almost exclusively involved only with 
the I/O Packet, the UCB, and the SCB. The entire structure has been 
presented to add depth to the driver writer's understanding of the I/O 
system, to emphasize the relationships among individual control 
blocks, and to further clarify the role a given driver fulfills in the 
processing of an I/O request. 
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CHAPTER 2 
INCORPORATING USER-WRITTEN DRIVERS INTO RSX-11M 



2.1 INTRODUCTION 

Though explicit details for writing a driver have not been presented, 
enough conceptual information now exists to consider incorporating a 
user driver into a system. This follows from the fact that many 
considerations for writing a driver are most easily presented within 
the context of the process followed for installing it. 

The reader is already assumed to be familiar with the RSX-llM System 
Generation Manual. 

Taken to n ether ,- Chapters 1 and 2 present a comprehensive overview of 
the relevant considerations for undertaking the implementation of a 
dr iver . 



2.2 OVERVIEW 

The user who has decided to add a driver to RSX-llM has concomitantly 
shared the responsibilities for the integrity of the Executive. 
Errors in this code can easily cause a system failure and bring to a 
halt all user service * 

The basic steps involved in creating and installing a user-written 
driver are as jlOxxOwsj 

1. Bootstrap the source disk and run Sysgen Phase 1. 

2. Bootstrap the object disk. 

3. Create the assembly source for the driver and its associated 
data structures. 

4. Run Sysgen Phase 2. 
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At the completion of Sysgen Phase 2, the user has a system with the 
user-written driver integrated into it. Since it is anticipated that 
a debugging sequence will be required to shake down the driver, the 
following sequence will result in an updated driver being incorporated 
into the existing system: 

1. Correct and re-assemble the driver and/or data structures. 

2. Run the Librarian to replace the old object modules in 
RSX11M.OLB with the repaired ones. 

3. Rebuild the Executive using RSXBLD.CMD. 

4. Using Virtual MCR, rebuild the system. 

5. Bootstrap the system. 

When adding a user-written driver to the system, the driver may be 
assembled to include padding space for possible expansion during the 
debugging process. 



2.3 INCORPORATING A DRIVER - DETAILS 



2.3.1 Creating the Data Structure 

The data structures associated with I/O drivers will be detailed in 
Chapter 3. Of the structures discussed, only three require assembly 
source: 

1. The DCB; 

2. UCB's, and 

3. SCB's. 

Within these control blocks, only those items which are static or 
require initialization are supplied in the source description. Listed 
below is an overview of the data fields the driver writer will be 
required to supply in the assembly source of his driver's data 
structure . 



2.3.1.1 Required Device Control Block (DCB) Fields - The required DCB 
fields are described below: 

D.LNK Link to next DCB. 

This field will be zero if this is the last DCB. If 
the user is incorporating more than one user-written 
driver at one time, then this field should point to 
another DCB in the DCB chain. 

D.UCB Address of the first UCB associated with this DCB. 

D.NAM Two-character ASCII generic device name. This name 
must be unique. 
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D.UNIT Highest and lowest unit numbers controlled by this DCB. 

D.UCBL Length of a UCB. 

If a given DCB has multiple UCB ' s , all UCB ' s must be of 
the same length. 

D.DSP Address of the driver dispatch table. 

The dispatch table is located within the driver code. 
This field will contain a global reference to the label 
associated with this table. 

D.MSK I/O function masks 

The user must supply bit-by-bit mapping for these four 
I/O function masks. Note that the format of the mask 
words is split into two groups of four words. 
Functions 0-15 are covered by the first group, and 
functions 16-31 by the second. 



2.3.1.2 Required Unit Control Block (UCB) Fields - The required UCB 
fields are described below: 

U.DCB Backpointer to the associated DCB. 

U.RED Initially contains the address of this UCB (i.e., 
redirect pointer). 

U.CTL Control bits that must be established by the driver 
writer with the UCB source. 

U.STS Unit status byte. 

U.UNIT Physical unit number serviced by this UCB. 

U.ST2 Unit status byte extension. 

U.CWl Characteristics word 1= Standard description (Chapter 
3) applies. 

U.CW2 Driver dependent. 

U.CW3 Driver dependent. 

U.CW4 Default buffer size. 

U.SCB Address of the SCB for this UCB. 

U.ATT TCB address of attached task. 
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2.3.1.3 Required Status Control Block (SCB) Fields - The required SCB 
fields are described below: 

S.LHD I/O Queue listhead. 

S.PRI Priority of interrupting source. 

S.VCT Interrupt vector address divided by 4. 

S.ITM Initial timeout count. 

S.CON Controller index (i.e., controller number multiplied by 
2) . 

S.STS Controller status. 

S.CSR Address of control and status register. 



2.3.1.4 Source Format of the Data Structure - A single DCB can 
service multiple UCB's and SCB's. The existence of multiple UCB ' s and 
SCB ' s is determined by the actual device subsystem being supported by 
a given driver on the user's operational hardware configuration. 
Figures 1-2 and 1-3 illustrate possible DCB, UCB, and SCB structural 
relationships. Typically, in writing a data structure source 
(DEC-suppl ied RSX-11H drivers use this scheme), the DCB is placed 
first, followed by the UCB(s), followed by the SCB(s). 



2.3.2 Creating the Driver Source Code 

Creating the source code to drive a device involves the following: 

1. Thorough reading and understanding of this manual; 

2. Detailed familiarization with the physical device and its 
operational characteristics; 

3. Determining the level of support required for the device; 

4. Creating the data structure source code for the device; 

5. Determining actions to be taken at the five driver entry 
points : 

a. Initiator; 

b. Cancel I/O; 

c. Timeout; 

d . Power fa il , and 

e. Interrupt. 

6. Creating the driver source code. 

Source code for the driver and data structure should be created on the 
object disk under UIC [200,200]. 
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2.3.3 Incorporating the User-Written Driver 

Incorporating a driver is accomplished via the standard system 

generation process. Phase i of system generation includes queries 

which condition Phase 2 for user-written driver inclusion. 
Specifically, the query 

ARE YOU PLANNING TO INCLUDE A USER WRITTEN DRIVER? [Y/N] : 

if answered affirmatively, results in a second query 

WHAT IS THE ADDRESS OF THE HIGHEST DEVICE INTERRUPT VECTOR? [0] : 

The answer to which is required so Phase 1 can allocate sufficient 
vector space to avoid run-time destruction of the system stack. 
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execution of Phase 2, the query 

*D0 YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]: 

is posed. If the answer is affirmative, then subsequent dialog guides 
the driver writer through the process of adding his driver to the 
generated system. Operations performed include assembly of the driver 
and its data structure, inclusion of the resultant object modules into 
the executive object module library, and editing of the RSX-llM task 
build command file. 

The following sample dialog illustrates the addition of a driver for 
device XX. All user responses are underl ined . The notation [l,2x] 
indicates that the appropriate UIC is to be substituted, viz., [1,20] 
for an unmapped system and [1,24] for a mapped system. 

>* DO YOU WISH TO ADD USER WRITTEN DRIVER(S) TO THE EXEC? [Y/N]:Y 

> SET /UIC=[200,200] 

>. 

>; WE WILL PAUSE WHILE YOU ASSEMBLE YOUR DRIVER (S) AND USRTB 
MODULE. THE EXEC ASSEMBLY PREFIX FILE RSXMC.MAC IS ALREADY 
LOCATED UNDER UIC [200,200]. ASSUMING YOUR DRIVER(S) NAME IS 
XXDRV, WHERE XX IS THE DEVICE NAME (E.G., DK) THE FOLLOWING 



> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

AT. — PAUSING. TO CONTINUE TYPE "RES ...AT." 

> RUN $MAC 

MAC > XXDRV= [1,1] EXEMC/ML, [200,200] RSXMC , XXDRV 

MAC > USRTB=[ 1,11 EXEMC/ML, [ 2 00 , 200 ] RSXMC , USRTB 

MAO~Z 



>RUN $MAC 

MAOXXDRV= [1,1] EXEMC/ML ,[200,200] RSXMC , XXDRV 
MAC >USRTB= [1,1] EXEMC/ML ,[200,200] RSXMC , USRTB 
MAC > ~ Z 
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> RES ...AT. 

AT. — CONTINUING 

>. 

NOW YOU MUST ADD YOUR DRIVER (S) AND USRTB MODULE 

TO THE EXEC OBJECT MODULE LIBRARY. THE FOLLOWING IS AN EXAMPLE: 



> 

> 

> 

> 

> 

> 

> SET /UIC=[l,2x] 

>LBR 



LBR>RSX11M/RP=[ 2 00, 200] XXDRV, USRTB 
LBR>~Z 



LBR> RSX11M/RP= [2 00 , 200 ] XXDRV, USRTB 
LBR>~Z 



> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> 

> EDI RSXBLD.CMD 

[PAGE 1] 

*PL TTDRV 

[ 1 , 2x] RSX11M/LB : TTDRV 

*I 

[1 , 2x] RSX11M/LB : XXDRV 

[1 , 2x] RSX11M/LB : LOADR: NULTK: SYSTB : SYTAB : INITL 

*C/SYSTB/SYSTB : USRTB/ 

[ 1 , 2x ] RSX11M/LB : LOADR : NULTK : SYSTB : USRTB : SYTAB : IN ITL 

* PL $USRTB 

GBLDEF=$USRTB:0 

*D 

*EX 

[EXIT] 

This completes the user-written driver section of Phase 2, which then 
continues . 



YOU MUST NOW ADD COMMANDS TO INCLUDE YOUR DRIVER (S) AND USRTB 
MODULE INTO THE EXEC BY EDITING THE EXEC TASK BUILD COMMAND FILE 
TO ADD DRIVER (S), INSERT COMMANDS OF THE FORM: 

[1,2x]RSX11M/LB: XXDRV 

INTO THE COMMAND FILE IN THE PLACE WHERE THE 

OTHER DRIVERS ARE REFERENCED. XXDRV REPRESENTS THE NAME OF 
YOUR DRIVER (S). IN ADDITION, LOCATE THE LINE IN WHICH THE 
MODULE SYSTB IS REFERENCED AND ADD A REFERENCE TO YOUR 
USRTB MODULE IMMEDIATELY AFTER IT. E.G.: 

[1 , 2x] RSX11M/LB : LOADR: NULTK: SYSTB : USRTB : SYTAB : INITL 

THEN LOCATE THE LINE: 

GBLDEF=$USRTB: 

AND DELETE IT. 
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2.4 DRIVER DEBUGGING 

Since the protection checks afforded user programs are not available 
to system modules, driver errors will be more difficult to isolate 
than user program errors. But conventional drivers, being modular and 
short, should be easily debugged. The following three sections 
describe a set of debugging tools and guidelines that should simplify 
the driver debugging process. 

Section 2.4.1 describes how to re-incorporate a driver into a system 
after a fault has been discovered. Section 2.4.2 describes the 
Executive Debugging Tool, and Section 2.4.3 provide some general hints 
for isolating faults in Executive software (of which drivers are a 
subset) . 



2.4.1 Rebuilding and Re-incorporating the User Driver 
Rebuilding and re-incorporation involves five steps: 

1. Correction and re-assembly of the driver and/or device data 
structures; 

2. Updating the Executive object module library; 

3. Rebuilding the Executive; 

4. Running Virtual MCR to rebuild the system, and 

5. Bootstrapping the new system. 



2.4.1.1 Re-Assembly - Assuming that the object system has been 
bootstrapped, appropriate volumes have been MOUnted, and the source 
code for the user driver and/or device data base has been updated, 
then : 

>RUN $MAC/UIC=[200,200] 



MAC > USRTB= [1 , 1 ] EXEMC/ML, [200,2001 RSXMC , USRTB 
MAC > lZ 

'ill effect the re-assembly of both the driver and data base 



2.4.1.2 Updating the Executive Object Module Library - After 

re-assembly of the user driver and/or data base, the Executive object 

module library must be updated. The following commands will 
accomplish this: 

> RUN $LBR/UIC=[l,2x] * 

LB R > RSX11M/RP= \ 2 00 , 200 1 XXDRV, USRTB 

LBR>~Z 



* 'x' is a '0' for an unmapped system and '4' for a mapped system 
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2.4.1.3 Rebuilding the Executive - Since an updated driver is to be 
inserted, the Executive, of which the driver is a part, must be 
relinked. To do this, enter the following commands: 

> RUN $TKB/UIC=[l,2x] * 

TKB> @RSXBLD 

TKB>~Z 



> RUN $PIP/UIO[l,5x] * 
PIP >RSX11M. SYS/NV=RSXllM. TSK 
PIP>~Z 



2.4.1.4 Incorporating Tasks into the System - Run Virtual MCR (VMR) 
using the dialog shown as a guide. On completion, the new system is 
ready for bootstrapping. The general procedure to follow is: 

1. Establish system partitions; 

2. Release all unused space to the dynamic storage region; 

3. Install tasks (at least FCP, INS, MOU, and MCR); and 

4. Exit from Virtual MCR and boot in the new system. 
VMR Example: 



> RUN $VMR/UIC=[1, 5x] * ! 
ENTER FILENAME: RSX11M. SYS 



VMR>SET/MAIN=SYSPAR:1300 



VMR>SET /MAIN=PAR14K:400 



VMR> SET /SUB=PAR14K:GEN :400:400 
VM P >SET /POOL = 400 



VMR>INS 


BOO 


VMR>INS 


DMO 


VMR > INS 


FCP 


VMR > INS 


IND 


VMR>INS 


INI 


VMR > INS 


INS 


VMR > INS 


MCR 


VMR>INS 


MOU 


VMR > I MS 


SAV 


VMR > INS 


TKN 


VMRMNS 


UFD 



VMR> Z 



RUN VIRTUAL MCR 

! VMR PROMPTS FOR FILE NAME 

100: TASK ! SET UP SYSTEM PARTITION 
! SET UP 14K PARTITION 
! SET UP 8K SUB PARTITION 



700:TASK 



ADD FREE SPACE TO POOL 

INSTALL BOOT 

INSTALL DISMOUNT 

INSTALL FILE SYSTEM 

INSTALL INDIRECT FILE PROCESSOR 

INSTALL INITVOLUME 

INSTALL INSTALL 

INSTALL MCR 

INSTALL MOUNT 

INSTALL SAVE 

INSTALL TASK TERMINATION TASK 

INSTALL USER FILE DIRECTORY BUILDER 

EXIT FROM VIRTUAL MCR 



2.4.1.5 Bootstrapping the New System - The new system may now be 
bootstrapped with the MCR Boot command, as shown below: 

>BOO [l,5x]RSXllM 



x 1 is a '0' for an unmapped system and '4' for a mapped system 
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2.4.2 RSX-llM Executive Debugging Tool 

An interactive debugging tool has been developed for RSX-llM to aid in 
the debuaaina of executive modules, I/O drivers, and interrupt service 
routines" This debugging aid is called XDT and is a version of PSX-11 
ODT, which does not contain the following features and commands: 

No $M - (MASK) register 

No $X - (Entry Flag) registers 

No $V - (SST vector) registers 

No $D - (I/O LUN) registers 

No $E - (SST data) registers 

No E (Effective Address Search) command 

No F - (Fill Memory) command 

No N - (Not word search) command 

No V - (Restore SST vectors) command 

No W - (Memory word search) command 

The X (Exit) and P (Proceed) commands have also been changed. The X 
command causes a jump to the crash reporting routine, and the P 
command will permit the user to proceed if an unknown breakpoint is 
encountered . 

Other than the omitted features and the change in the definition of 
the X and P commands, XDT is command-compatible with RSX-11 ODT, and 
the RSX-11 ODT Manual may be used as a guide to its operation. 

XDT may be included in a system during Phase 1 of system generation. 

■"■' c -3 — — - 2 • 

DO YOU WANT TO INCLUDE THE EXECUTIVE DEBUGGING TOOL? [Y/N]: 

is posed. If the answer is affirmative, then XDT is automatically 
included in the generated system. When the resultant system is 
bootstrapped, XDT gains control and types: 

XDT: <system version> 

followed by the prompting symbol 

XDT> 

on the console terminal. Breakpoints may be set at this time, and 
then a G command may be given, returning control to the RSX-llM 
Executive initialization code. Whenever a breakpoint is reached, a 
printout similar to that of RSX-11 ODT will occur. 
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A forced entry to XDT can be executed at any time from a privileged 
terminal via the MCR Breakpoint (BRK) command. Thus, the normal 
procedure is to type G when the system is bootstrapped without setting 
any breakpoints. When it becomes necessary to use XDT, the MCR 
Breakpoint command is executed, causing a forced breakpoint. XDT then 
pr ints : 

BE: xxxxxx 

followed by the prompting symbol 

XDT> 

on the console terminal. Breakpoints and/or other XDT commands may 
then be executed. System operation may be continued by typing the P 
(Proceed) command to XDT. 

Note that XDT runs entirely at priority level 7 and does not interfere 
with user level RSX-11 ODT. In other words, user level RSX-11 ODT can 
be in use with several tasks, while XDT is being used to debug 
Executive modules. 

All XDT command I/O is done via the console terminal,, and the L (List 
Memory) command can list on either the console or the line printer. 



2.4.3 Fault Isolation - Some General Hints 



2.4.3.1 Introduction - Adding a user-written driver carries with it 
the risk of introducing obscure bugs into an RSX-llM system. Since 
the driver runs as part of the Executive, these bugs are often 
difficult to diagnose. It is extremely important that the driver 
writer develop the skills and discipline needed to rapidly isolate the 
source of a system failure. 



2.4.3.2 Fault Classifications - Four culprits can be identified when 
the system faults: 

1. A user-state task has faulted such that it causes the system 
to fault; 

2. The user-written driver has faulted such that it causes the 
system to fault; 

3. The RSX-llM system software itself has faulted, or 

4. The host hardware has faulted. 

The immediate action on the part of the driver-writer subject to one 
of these errors is to determine which of these four cases is the 
source of the fault. Of prime concern will be the procedures which 
may help the driver writer uncover the fault source. The repair of 
the fault itself is assumed to be the driver writer's responsibility. 



2-10 



INCORPORATING USER-WRITTEN DRIVERS INTO RSX-11M 

Faults manifest themselves in roughly three ways (they are listed here 
in order of increasing difficulty of isolation) : 

1. The system displays the CRASH printout and halts or, if XDT 
has been included", an unintended trap to XDT occurs. 

2. The system halts but displays nothing. 

3. The system is in an unintended loop. 



2.4.3.3 Immediate Servicing - RSX-11M can be built to contain 
resident crash reporting and panic dump routines; the following 
discussions assume the existence of such a system. (Note that the 
minimal system will not have space for these routines). Section 2.5 
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The immediate aim, regardless of the fault manifestation, is to 
initiate the crash reporting and panic dump routines. 

CASE 1 - The system has trapped to XDT: 

The trap may or may not be intended (e.g., a previously set 
breakpoint). If it is not intended, type the X command, causing XDT 
to exit to the crash reporting routine; if, however, the source of 
the t obi em is suspected (for example, a recent coding change), then 
pertinent data structures and code may be examined using XDT. 

CASE 2 - The System Has Displayed the Crash Printout: 

In this case, all the basic information describing the state of the 
system has been displayed. The actual Crash printout will be 
described after learning how to invoke Panic Dump for cases 3 and 4 
(see below) . 

CASE 3 - The System Has Halted - No Information Displayed: 

Before taking any action, preserve the current PS and PC and the 
pertinent device registers (i.e., examine and record the information 
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PDP-11 processor. Consult the appropriate PDP-11 Processor Handbook 
for details. 

After obtaining the PS and PC, invoke the Panic Dump Routine by 
entering 40(8) in the switch register, depressing LOAD ADDR, and then 
START. 

The value 40(8) is the address of a JMP to the Panic Dump Routine in 
all RSX-11M systems. 

The Panic Dump Routine saves registers R0 through R6 and then halts, 
awaiting dump limits to be entered via the console switch register. 
The PS is cleared when START is depressed, and the original PC is 
destroyed; thus, the importance of recording these vital pieces of 
debugging information before initiating the Panic Dump Routine should 
be recognized. 
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Dumps of selected blocks of memory may be obtained using the following 
procedure: 

1. Enter the low dump limit in the console switch register and 
depress CONT. The processor will immediately halt again. 

2. Enter the high dump limit in the console switch register and 
depress CONT. The dump will begin on the device whose CSR 
address is D$$BUG (usually 177514, which is the line 
printer) . The actual value of D$$BUG is determined during 
system generation when answering the panic dump question. At 
the end of the dump, the processor will again halt, awaiting 
the input of another set of dump limits. 

To reach the same status arrived at with crash reporting in 
Case 2 above, enter the dump limits 0-520(8) when the panic 
dump routine first halts. This will dump the system stack 
and the general registers. The limit 520(8) changes if the 
highest interrupt vector is above 400(8). The actual upper 
limit is always the value of the global symbol $STACK and may 
be obtained from the module LOWCR in the Executve memory 
allocation map. 

CASE 4 - System Is in an Unintended Loop: 

Proceed as follows: 

1. Halt the processor 

2. Record PC, PS, and any pertinent device registers, as in case 
3 above. 

After recording the PS and PC, the driver-writer may want to step 
through a number of instructions in an attempt to locate the loop. 

After the attempt to locate the loop, transfer to the panic dump 
routine as in Case 3. 

This brings us to an equivalent status for the three fault situations. 



2.4.3.4 Other Pertinent Fault Isolation Data - Before proceeding with 
the task of locating the fault, the driver-writer is strongly advised 
to dump system common (SYSCM) . This can be accomplished by looking 
for the module SYSCM in the Executive memory allocation map and 
entering the appropriate limits to the Panic Dump Routine. SYSCM 
contains a number of critical pointers and listheads. 

In addition, the driver-writer should dump the dynamic storage region 
and the device tables. The dynamic storage region is the module INITL 
and the device tables are in SYSTB. 

The driver-writer now has: 

PS 

PC 

The Stack 
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RO through R6 

Pertinent device registers 
The dynamic storage region 
The device tables, and 
System common. 
This data is a minimal requirement for effective fault isolation. 



2.4.3.5 Fault Tracing - Three pointers in SYSCM are critical in fault 
tracing. These pointers are described below: 

$STKDP - Stack Depth Indicator 

This data item will indicate which stack was being used at the 
time of the crash. As will be seen, this plays an important role 
in determining the origin of a fault. The following values 

apply: 

+1 - User (task state) stack 

or less - System stack 

If the stack depth is +1, then the user has managed to crash the 

system. In a system with brickwall protection (for example, the 

mapped RSX-llM system), the non-privileged user should not be 
able to crash the system. 

$TKTCB - Pointer to the Current Task Control Block (TCB) 

This is the TCB of the user level task in control of the CPU. 

SHEADR - Pointer to the Current Task Header, 

Locating the task header provides additional data. The first 
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was saved. If the user branches wildly into the Executive, it 
will terminate the user task, but the system will continue to 
function (possibly erroneously). Knowing the user's stack 
pointer provides one more link in the chain which may lead to the 
resolution of the fault. 

The header (as pointed to by $HEADR) also contains the last saved 
register set, just before the header guard word, which is the 
last word in the header and is pointed to by H.GARD. 
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H . NLUN 
H . GARD 

H.HDLN 



RO 



Rl 



R2 



R3 



LENGTH IN BYTES 



SP 



PS 



PC 



R5 



R4 



Figure 2-1 
Unmapped System Header 
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RO 



H.NLUN 
H . GARD 



R5 



PC 



PS 



H.HDLN 



LENGTH IN BYTES 



SP 



Figure 2-2 
Mapped System Header 



A. Tracking Faults Following Automatic Display of System State (Cases 
1 and 2) : 



Firs l examine <_ue sys<_em stscK pointer • uSU3j.j.y an uxec 
is the result of an SST type trap within the Executive. 



ve 



t- ra t 1 n V" £1 



If an SST does occur witmn tne Executive, tnen tne origin or tne can 
on the crash reporting routine will be in the SST service module. 
(The crash call is initiated by issuing an IOT at a stack depth of 
zero or less) . 

A call to crash also occurs in the Directive Dispatcher when an EMT 
was issued at a stack depth of zero or less, or a trap instruction was 
executed at a depth of less than zero. The stack structure in the 
case of an internal SST fault is shown in Figure 2-3. 



2-15 



INCORPORATING USER-WRITTEN DRIVERS INTO RSX-11M 



PS 



PC 



R5 



R4 



R3 



R2 



Rl 



RO 



RETURN TO SYSTEM EXIT 



ZERO OR MORE SST PARAMETERS 



SST FAULT CODE 



NUMBER OF BYTES 



SP 



Figure 2-3 
Stack Structure - Internal SST Fault 



The fault codes are: 



0. 

2. 

4. 

6. 

8. 

10 

12, 

14 

16 

18 

20 

22 

24 

26 

28 



ODD ADDRESS AND TRAPS TO 4 

MEMORY PROTECT VIOLATION 

BREAK POINT OR TRACE TRAP 

IOT INSTRUCTION 

ILLEGAL OR RESERVED INSTRUCTION 

NON RSX EMT INSTRUCTION 

TRAP INSTRUCTION 

11/40 FLOATING POINT EXCEPTION 

SST ABORT-BAD STACK 

AST ABORT-BAD STACK 

ABORT VIA DIRECTIVE 

TASK LOAD READ FAILURE 

TASK CHECKPOINT READ FAILURE 

TASK EXIT WITH OUTSTANDING I/O 

TASK MEMORY PARITY ERROR 



The PC points to the instruction following the one which caused the 
SST failure. The number of bytes is the number of bytes that are 
normally transferred to the user stack when the particular type of SST 
occurs. If the number is 4, then just the PS and PC are transferred 
and there are no SST parameters. 

If the failure is detected in $DRDSP, the stack is the same as Figure 
2-3, except the number of bytes, SST fault code (the fault codes are 
listed above) , and SST parameters are not present. The crash report 
message, however, will indicate that the failure occurred in $DRDSP. 
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There is one SST-type failure, stack underflow, that will not have the 
stack structure of Figure 2-3. To determine where the crash occurred, 
first establish the stack structure; this can be deduced by the value 
of the stack pointer (SP) and the contents of the top word on the 
stack. If the stack structure is that of Figure 2-3, then the failure 
occurred in $DRDSP, or was a normal SST crash. If the stack structure 
is determined to be that of Figure 2-4, then a non-normal SST crash 
has occurred. 



SP 



PS 



PC 



Figure 2-4 
Stack Structure - Non-Normal SST Fault 



Non-normal SST failures occur when i 
information on the stack without forcing 
occurs, a direct jump to the crash repor 
than an IOT crash. The PS and PC on the 
crash, and the address printed out by th 
the address of the fault rather th 
crashes the system. Note that the crash 
PC and PS of the IOT instruction from th 
incorrect. Thus, the stack pointer will 
it really is (i.e., as in Figure 2-4). 



t is not possible to push 

another SST fault. When this 
ting routine is made rather 

stack are those of the actual 
e crash reporting routine is 
an the address of the IOT that 

reporting routine removes the 
e stack, which in this case is 

appear to be 4 greater than 



The driver writer now has all the information needed to isolate the 
cause of the failure. From this point on, one must rely on personal 
experience and a knowledge of the interaction between the driver and 
the services provided by the Executive. 

B. Tracking Faults When the Processor Halts Without Providing Fault 
Display: 

Tracking starts with an examination of $STKDP, $TKTCB, and $HEADR. 
The difficulty in tracking failures in this case is that the system 
stack is not directly associated with the cause of a failure. 

By examining $STKDP, one can determine the system state at the time of 
failure. If it was in user state, the next step is to examine the 
user's stack. The examination process focuses on scanning the stack 
for addresses which may turn out to be subroutine links which will 
ultimately lead to a thread of events isolating the fault. This is 
essentially the same aim in looking at the system stack if $STKDP is 
zero or less. 

Frequently, a fault will occur such that the SP points to Top of Stack 
(T0S)+4. This results from issuing an RTI when the top two items on 
the stack are data; this will result in a wild branch, then, most 
probably, a halt. Figure 2-5 shows a case, where two data items are 
on the stack when the programmer executes an RTI. TOS points to a 
word containing 40100. Suppose that location 40100 contains a halt. 
This indicates that the original SP was four bytes below the final SP, 
and fault tracing should begin from the previous SP. 
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40100 



SP 



SP 



Figure 2-5 
Stack Structure - Data Items on Stack 



This type of fault also occurs when an RTS instruction is executed 
with an inconsistent stack. However, in this case SP will point to 
TOS+2. 

A scan of the contents of the general registers may give some hint as 
to the neighborhood in which a fault (or the sequence of events 
leading up to the fault) occurred. 

If the fault occurred in a new driver, a frequent source of clues is 
the buffer address and count words in the UCB (U.BUF, U.BUF+2, U.CNT), 
as are the activity flags (US.BSY and S.STS). Other locations in both 
the UCB and SCB may also provide information that may help locate the 
source of the fault. 

C. Tracking Faults When an Un-Intended Loop Has Occurred: 

After halting the processor, the same state exists as in the preceding 
section. Some specific suggestions are to check for a stack overflow 
loop. Patterns of data successively duplicated on the stack indicate 
a stack looping failure. 



D. 



Additional Hints 



Also of value is the current (or last) I/O Packet, the address of 
which is found in S.PKT of the SCB. The packet function (I.FCN) will 
define the last activity performed on the unit. 

If trouble occurred in terminating an I/O request, a scan of the 
system dynamic memory region may provide some insight. This region 
starts at the address contained in $CRAVL, a cell in SYSCM. Since all 
I/O packets are built in system dynamic memory, when they are 
successfully terminated, their memory is returned to the dynamic 
memory region. Following the link pointers in this region may reveal 
whether or not I/O completion proceeded to that point. A frequent 
error for an inter rupt-dr iven device is to terminate an I/O Packet 
twice when the device is not properly disabled on I/O completion and 
an unexpected interrupt occurs. This ultimately produces a double 
de-allocation of the same packet memory. Double de-allocation of a 
dynamic buffer in RSX-11M causes a loop in the module $DEACB on the 
next de-allocation (of a block of higher address) after the second 
de-allocation of the same block. At that time, R2 and R3 both contain 
the address of the I/O Packet memory which has been doubly 
de-allocated . 
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2.5 SAMPLE OUTPUT FROM CRASH AND PANIC DUMP ROUTINES 

2.5.1 Crash Output 

A sample of Crash output is shown below: 

SYSTEM CRASH AT LOCATION 047622 

REGISTERS 

R0=000340 Rl=177753 R2=000353 R3=0000u0 

R4=000004 R5=046712 SP=000472 PS=000340 
SYSTEM STACK DUMP 

LOCATION CONTENTS 

000472 000004 

000474 000000 

000476 001514 

000500 000340 

000502 177753 

000504 000353 

000506 000000 

000510 000000 

000512 057750 

000514 002504 

000516 030011 

000520 100340 

000522 000340 

)00524 056446 

000526 000000 

000530 102144 

000532 000000 

000534 101376 

000536 101372 

000540 102022 



2.5.2 Panic Dump Output 

A portion of the output from Panic Dump is shown below. Output is in 
three line groupings. In the left-hand column, two addresses are 
shown. The first address is the absolute address; the second address 
is the dump relative address. The first line in a 3-line group is the 
octal word value; the second line is the two octal byte values of the 
word; the third line contains the ASCII representation of the bytes. 
The ASCII representations are reversed to improve readability. The 
first output grouping from Panic Dump displays, proceeding from right 
to left, PS, R0, Rl, R2, R3 , R4 , R5, and the SP. 
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000544 000000 046076 000066 000000 000000 000000 000000 045316 

000000 000 000 114 076 000 066 000 000 000 000 000 000 000 000 112 316 

"@ ~@ > L 6 ~@ ~@ ~(a ~@ ~@ ~@ ~@ ~@ ~@ N J 



000000 022646 000340 045770 000340 045770 000340 045770 000340 

000000 045 246 000 340 113 370 000 340 113 370 000 340 113 370 000 340 

& % ~@ K ~@ K "<§ K ~@ 

000020 045776 000340 011124 000340 045770 000340 050500 000340 

000020 113 376 000 340 022 124 000 340 113 370 000 340 121 100 000 340 

K ~@ T ~R ~@ K ~@ @ Q ~@ 

000040 000167 000543 000001 000001 000000 000000 000000 000353 

000040 000 167 001 143 000 001 000 001 000 000 000 000 000 000 000 353 

"@ "A "A ~@ "A ~@ ~@ ~@ ~@ ~@ ~fl ~a ~Q 



000060 035444 000340 034034 000340 032776 000340 032402 000340 
000060 073 044 000 340 070 034 000 340 065 376 000 340 065 002 000 340 
$ ; ~@ ~\ 8 ~@ 5 ~@ ~B 5 ~@ 
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CHAPTER 3 
WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS 

In Chapter 1, overviews were given for: 

Data structures; 

Executive services, and 

Programming protocol. 

In this chapter, the details for the data structures and Executive 
services are given. The protocol coverage in Chapter 1 was, however, 
detailed enough to make further elaboration of programming protocol 
unnecessary. 

3.1 DATA STRUCTURES 

Of all the control blocks in the I/O data structure, only four are of 
direct concern to a driver writer: 

1. The I/O Packet; 

2. The DCB; 

3. The UCB, and 

4. The SCB. 

Although the data structures contain an abundance of data pertaining 
to input/output operations, drivers per se are involved only with a 
subset of this data. Most of the data which requires the driver 
writer's attention is supplied in the data structure source code, and 
is not referenced during driver execution. Such an item is classified 
as: 

initialized , not referenced>* 



* The first field states whether the field is initialized in the data 
structure source, and the second field gives the typical access at 
execution time. 
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Fields supplied statically in the source code at the creation of the 
data structure, and subsequently referenced during driver execution, 
are classified: 

<initial ized , read-only>. 

Fields set up during driver execution are classified: 

<not initialized, read-only> 

This form implies that either an agent other than the 
driver has established the field or that the driver has 
set it up once and references it read-only thereafter. 

or : 

<not initialized, read-write>. 

Fields which do not involve the driver writer at any level are 
classified 

<not initialized, not-referenced> . 

These classifications cover most-likely cases, since exceptions do 
exist and are appropriately noted. 



3.1.1 The I/O Packet 

Figure 3-1 is a layout of the 18-word I/O Packet which is constructed 
and placed in the driver I/O queue by QIO directive processing and 
subsequently delivered to the driver by a call to $GTPKT. Figure 3-2 
is the DPB from which the I/O Packet is generated. 



* The first field states whether the field is initialized in the data 
structure source, and the second field gives the typical access at 
execution time. 
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I.LNK 
I.EFN 
I.PRI 

I.TCB 

I . LN2 

I.UCB 

I.FCN 

I.IOSB 



LAST 

I.PRM 



LINK TO NEXT I/O PACKET 



EFN 



PRI 



TCB ADDRESS OF REQUESTER 



ADDRESS OF SECOND LUT WORD 



ADDRESS OF REDIRECT UCB 



FUNCTION CODE 



MODIFIER 



VIRTUAL ADDR OF I/O STATUS BLK 



RELOCATION BIAS OF IOSB 



REAL ADDRESS OF IOSB 



VIRTUAL ADDR OF AST SERVICE RTN 



DEVICE 
PARAMETERS 



Figure 3-1 
I/O Packet Format 
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3.1.1.1 I/O Packet Details - The I/O Packet is built dynamically by 
QIO directive processing. Thus, no static fields exist with respect 
to a driver. I/O Packets are created dynamically and, therefore, the 
first parameter does not apply. Fields in the I/O Packet (described 
below) are classified as: 

Not referenced, 
read-only, or 
read/wr ite . 

I.LNK 

Driver access: 

Not referenced. 

Description: 

Links I/O Packets queued for a driver. A zero ends the 
chain. The listhead is in the SCB (S.LHD). 

I.PRI 

Driver access: 

Not referenced. 

Description: 

Priority copied from the TCB of the requesting task. 

I.EFN 

Driver access: 

Not referenced. 

Descr iption : 

Contains the event flag number as copied by QIO directive 
processing from the requester's DPB . 

I. TCB 

Driver access: 

Not referenced. 

Descr iption : 

TCB address of the requesting task. 

I.LN2 

Driver access: 

Not referenced. 
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Descr iption: 

Contains the address of the second word of the LUT entry in 
the task header to which the I/O request was directed. For 
open files on file-structured devices, this word contains the 
address of the Window Block; otherwise, it is zero. 

I.UCB 

Driver access: 

Not referenced. 

Descr iption: 

Contains the address of the Redirect UCB if the starting UCB 
has been subject to an MCR Redirect command * 

I.FCN 

Driver access: 

Read-only. 

Description: 

Contains the function code (see Table 3-1) for the I/O 
request . 

I.IOSB 

Driver access: 

Not referenced. 

Description: 

I.IOSB contains the virtual address of the I/O Status block 
(IOSB) , if one is specified, or zero if not. 

T T /"\ o D ji O -*r.A T mt!DJ.^ r-> s\ r^ +- •= i *■> 4-l->« r>AArae?a A f\ n K 1 a t.r/-> t- A fnr ■f-Vio 

i, lUODTi ailCl 1. IWDU i 1 ^Ulltaill Hie <u\w~i i. <i. <J >j ^\yu»^-i.v_rTVi.^ j_v ». »n<>- 

IOSB (see Appendix A for a detailed description of the 
address doubleword) . On an unmapped system, the first word 
is zero; the second word is the real address of the IOSB. 

In a mapped system, the first word contains the relocation 
bias of the IOSB; the bias is, in effect, the 32-word block 
number in which the IOSB starts. This block number is 
derived by viewing available real memory as a collection of 
32-word blocks numbered consecutively, starting with 0. 
Thus, if the IOSB starts at physical location 3210(8), its 
block number is 32(8). 

The second word is formatted as follows: 

Bits 0-5 Displacement in block (DIB) 
Bits 6-12 All zeros 
Bits 13-15 6 

The displacement in block is the offset from the block base. 
In the above example where the IOSB started at 3210(8), the 
DIB is equal to 10 (8) . 
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The value 6 in bits 13-15 is constant. It is used to cause 
an address reference through Kernel Page Address Register 6. 
Again, see Appendix A for details. 

The deferral of a discussion of the address doubleword to an 
appendix reflects the fact that a writer of a conventional 
driver has almost no need to concern himself with the 
contents or format of the address doubleword. Its 
construction and subsequent manipulation are normally 
external to the driver; subroutines are provided as 
Executive services for programmed I/O to render the 
manipulations of I/O transfers transparent to the driver 
itself. 



LAST 



Driver access: 

Not referenced. 

Descr iption : 

Contains the virtual address of the AST service routine to be 
executed at I/O completion. If no address is specified, the 
field contains zero. 

I . PRM 

Driver access: 

Not initialized, read-only. 
Descr iption : 

Device dependent parameters copied from the DPB. 

The QIO Directive Parameter Block (DPB) is constructed as shown in 
Figure 3-2. 



3-6 



WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS 



LENGTH 


DIC 


FUNCT CODE 


MODIFIER 


RESERVED 


LUN 


PRIORITY 


EFN 


I/O STATUS BLOCK ADDRESS 


AST ADDRESS 


DEVICE 


DEPENDENT 


PARAMETERS 









Figure 3-2 
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The parameters in the DPB have the following interpretation. 

Length (required) : 

The length of the DPB, which for the RSX-11M QIO directive, is 
always fixed at twelve words. 

DIC (required) : 

Directive Identification Code. For the QIO directive, this value 
is a 1. 

Function Code (required) : 

The code of the requested I/O function (0 thru 31.). 
Modifier : 

Device dependent modifier bits. 
Reserved : 

Reserved byte and must not be used. 
LUN (required) : 

Logical Unit Number. 

Pr ior ity: 

Request priority. Ignored by RSX-11M, but space must 
be allocated for RSX-llD compatibility. 

EFN (optional) : 

Event flag number. 

I/O Status Block Address (optional) : 

This word contains a pointer to the I/O status block, which is a 
2-word, device-dependent I/O completion data packet formatted as: 

Byte 

I/O status byte. 
Byte 1 

Augmented data supplied by the driver. 

Bytes 2 and 3 

The contents of these bytes depend on the value of byte 0. 

If byte 0=1, then these bytes usually contain the 

processed byte count. If byte does not equal zero, then 
the contents are device dependent. 

AST Address (optional) : 

Address of an AST service routine. 
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Device Dependent Parameters: 

Up to six parameters specific to the device and I/O function to 
be performed. Typically, for data transfer functions, these are: 

Buffer address 

Byte count 

Carriage control type 

Logical block number 

Any optional parameters that are not specified should be filled with 
zeros. 

3.1.2 The Device Control Block (DCB) 

Figure 3-3 is a schematic layout of the DCB. The DCB describes the 
static characteristics of a device controller and the units attacned 
to the controller. All fields must be specified. 



D . LNK 

D.UCB 

D.NAM 

D.UNIT 

D.UCBL 

D.DSP 

D.MSK 



LINK TO NEXT DCB (0=LAST) 



LINK TO FIRST UCB 



GENERIC DEVICE NAME 



HIGHEST UNIT # 



LOWEST UNIT # 



LENGTH OF UCB 



ADDR OF DRIVER DISPATCH TABLE 



LEGAL FCN MSK BITS 0-15. 



CONTROL FCN MSK BITS 0-15. 



NO-OP 'ED FCN MSK BITS 0-15. 



ACP FCN MSK BITS 0-15. 



LEGAL FCN MSK BITS 16.-32. 



CONTROL FCN MSK BITS 16.-32 



NO-OP 'ED FCN MSK BITS 16.-32. 



ACP FCN MSK BITS 16.-32. 



Figure 3-3 
Device Control Block 
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3.1.2.1 DCB Details - The fields in the DCB are described below: 

D.LNK (Link to next DCB)* 

Driver access: 

Initialized, not referenced. 

Description: 

Address link to the next DCB. A zero in this field indicates 
the last DCB in the chain. The driver writer links his DCB 
into the system DCB ' s via the global label $USRTB on his 
first DCB. 

D.UCB (Pointer to First UCB) 

Driver access: 

Initialized, not referenced. 

Description: 

Address link to the first and, possibly, the only UCB 
associated with the DCB. All UCB's, for a given DCB, are in 
contiguous memory locations and must all be the same length. 

D.NAM (ASCII Device Name) 

Driver access: 

Initialized, not referenced. 

Description : 

Generic device name in ASCII by which device units are 
mnemonically referenced. 

D.UNIT (Unit Number Range) 

Driver access: 

Initialized, not referenced. 

Description: 

Unit number range for the device. This range covers those 
logical units available to the user for device assignment. 
Typically, the lowest number is zero, and the highest is n-1, 
where n is the number of device-units described by the DCB. 

D.UCBL (UCB Length) 
Driver access: 

Initialized, not referenced. 



* Parenthesized contents indicate value to be initialized in the data 
base source code. 
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Description: 

The UCB may have any length to meet the needs of the driver 
for variable storage. However. all UCB ' s for a given DCB 
must have the same length. 

D.DSP (Dispatch Table Pointer) 

Driver access: 

Initialized, not referenced. 

Description: 

Address of the driver dispatch table. 

rYiicn liic i_/Acv^ u i. x v c nionco t_v-> ciuci tuc ul ivci ci v. any u ±. (.lie 

four entry points contained in the driver dispatch table, it 
accesses D.DSP, locates the appropriate address in the table, 
and calls the driver at that address. Thus, null addresses 
are not permitted. If the driver does not process a given 
function, then it simply returns. The driver writer must 
provide a driver dispatch table in the driver source. The 
label on this table is of the form $nnTBL and must be a 
global label. The designation nn is the 2-character generic 
device name for the device. Thus, $TTTBL is the global label 
on the driver dispatch table for the generic device name TT. 
This table is an ordered, 4-word table containing the 
following entry points: 

I/O Initiator; 

Cancel I/O; 

Device Timeout, and 

Power failure. 

When a driver is entered at one of these entry points, entry 
conditions are as follows: 

At Initiator: 

If UC.QUE=1 

R5 = UCB address 

Rl = Address of the I/O Packet 

If UC.QUE=0 

R5 = UCB address 

Interrupts are allowed. 

At Cancel I/O: 

R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

Rl = Address of TCB of current task 

RO = Address of active I/O packet 

Device interrupts are locked out. 
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At Device Timeout: 

R5 = UCB address 

R4 = SCB address 

R3 = Controller index 

RO = I/O status code IE.DNR (Device Not Ready) 

Device interrupts are locked out. 

At Power Failure: 

R5 = UCB address 
R4 = SCB address 
R3 = Controller index 

Interrupts are allowed. 

D.MSK (Function Masks) 

Driver access: 

Initialized, not referenced. 

Description: 

There are eight words, beginning at D.MSK, which are of 
critical importance to the proper functioning of a device 
driver. The Executive uses these words to validate and 
dispatch the I/O request specified by a QIO directive. The 
description which follows applies only to non-file-structured 
devices, since directions for writing drivers for 
file-structured devices (drivers which interface to FCP) are 
not included in this manual. Four masks, 2-words per mask, 
are described by the bit configurations established by the 
driver writer for these words. 

1. Legal function mask; 

2. Control function mask; 

3. No-op'ed function mask, and 

4. ACP function mask. 

The QIO directive allows for 32 possible I/O functions. The 
masks, as stated, are filters to determine validity and I/O 
requirements for the subject driver. 

The function value in the I/O request is filtered by the 
Executive through the four mask words. I/O function codes 
range from 0-31. If the function corresponds to a true 
condition in a mask word, a bit is set in the mask in the 
position which numerically corresponds to the function code. 
Thus, if the function 5 is legal, then bit 5 in the Legal 
Function Mask is set. 

The masks are laid out in memory in two 4-word groups. Each 
4-word group covers 16 function codes. The first four words 
cover the function codes 0-15; the second four words cover 
codes 16-31. Below is the exact layout used for the driver 
example in Chapter 5. 
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. WORD 


140033 


.WORD 


30 


.WORD 


140000 


• WORD 


n 


.WORD 


5 


.WORD 





.WORD 


1 


.WORD 


4 



LEGAL FUNCTION MASK CODES 0-15. 
CONTROL FUNCTION MASK CODES 0-15. 
NO-OP' ED FUNCTION MASK-CODES 0-15. 
ACP FUNCTION MASK CODES 0-15, 
LEGAL FUNCTION MASK CODES 16.-31. 
CONTROL FUNCTION MASK CODES 16.-31. 
NO-OP "ED FUNCTION MASK CODES 16.-31. 
ACP FUNCTION MASK CODES 16.-31. 



The mask words filter sequentially as follows: 

Legal Function Mask: 

Legal function values have the corresponding bit position in 
this word set to 1. Function codes that are not legal are 
rejected by QIO directive processing by returning IE.IFC in 

lie J-/'-' SUdLUS uiuuN/ jjjl <-» v J.U eU an j.\jod aucn-coo wdo opcomcui 

Control Function Mask: 

If any device-dependent data exists in the DPB, and this data 
does not require further checking by the QIO directive 
processor, the function is considered in the class <control 
function>. Such a function allows QIO directive processing 
to copy the DPB device-dependent data directly into the I/O 
Packet. 

No-op* ed Function Mask: 

A no-op function is any function that is considered 
successful as soon as it is issued. If the function is a 
no-op, QIO directive processing immediately marks the request 

successful; no additional filtering occurs. 

ACP Function Mask: 

If a function code is legal, but neither control nor no-op, 
then it is either an ACP function or a transfer function* If 
a function code may require intervention of an Ancillary 
Control Processor (ACP) , the corresponding bit in the ACP 
function mask must be set. 

In the specific case of read/write virtual functions, the 
corresponding mask bits may be set at the driver writer's 
option. If the corresponding mask bits for a read/write 
virtual function are set, QIO directive processing will 
recognize that a file-oriented function is being requested to 
a non-file-structured device and convert the request to a 
read/write logical function. 

This conversion is particularly useful. Consider a 

read/write virtual function to a specific device: 

1. If the device is file-structured and a file is open 
on the specified LUN, the block number specified is 
converted from a virtual block number in the file to 
a logical block number on the medium, and the request 
is queued to the driver as a read/write logical 
function. 

2. If the device is file-structured and no file is open 
on the specified LUN, then an error is returned and 
no further action is taken. 
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3. If the device is not file-structured, then the 
request is simply transformed to a read/write logical 
function and queued to the driver. (Specified block 
number is unchanged). 

Transfer Function Processing 

Finally, if the function is not an ACP function, then, by 
default, it is a transfer function. All transfer functions 
cause the QIO directive processor to check the specified 
buffer for legality (i.e., being within the address space of 
the requesting task) and proper alignment (i.e., word or 
byte). Also, the number of bytes being transferred is 
checked for proper modulus (i.e., nonzero and a proper 
multiple) . 



Mask Word Creation 

The creation of the function mask words involves three steps: 

1. Establish the I/O functions available on the device for which 
driver support is to be provided. 

2. Check the standard RSX-11M function code values in Table 3-1 
for equivalencies. Only function code is mandatory. 
Function codes 3 and 4, if used, must have the RSX-11M system 
interpretation. It is suggested that functions having an 
RSX-11M system counterpart use the RSX-11M code, but this is 
not required, except in the case where the device is to be 
used in conjunction with an ACP. From the supported function 
list, the two legal function mask words can be built. 

3. Given the legal function mask, 

3a. The Control Function mask is built by asking: 

Does this function carry a standard buffer address and 
byte count in the first two device-dependent parameter 
words? 

If it does not, then it either qualifies as a control 
function, or the driver itself must effect the checking and 
conversion of any addresses to the format required by the 
driver. (Buffer addresses in standard format are 
automatically converted to Address Doubleword format.) 

Control functions are, essentially, those whose DPB ' s do not 
contain buffer addresses or counts. 

3b. The No-op Function Mask is created by deciding which legal 
functions are to be no-op'ed. Typically, for File Control 
Services (FCS) compatibility on non-file-structured devices, 
the file access/deaccess functions are selected as legal 
functions, even though no specific action is required to 
access or deaccess a non-file-structured device; thus, the 
access/deaccess functions are no-op'ed. 

3c. Finally, the ACP functions Write Virtual Block and Read 
Virtual Block may be included. Other ACP functions that 
might be included fall into the non-conventional driver 
classification and are beyond the scope of this document. 
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3,1.2,2 I/O Function Codes - The filtering process which cascades 
through the function mask words in the DCB uses the function code byte 
supplied in the QIO directive DPB as the match value. Table 3-1 
contains the function code values used for DEC-supplied drivers. 



Table 3-1 
Standard I/O Function Codes 



FUNCTION 


EQUATED 


I/O 


VALUE (8) 


SYMBOLIC 


FUNCTION 





IO.KIL 


Cancel I/O 


1 


IO.WLB 


Write Logical Block 


2 


IO.RLB 


Read Logical Block 


3 


10. ATT 


Attach Device 


4 


IO.DET 


Detach Device 


5 




Unused 


6 




Unused 


7 




Unused 


10 




Unused 


11 


IO.FNA 


Find File in Directory 


12 




Unused 


13 


IO.RNA 


Remove File from Directory 


14 


IO.ENA 


Enter File in Directory 


15 


IO.ACR 


Access File for Read 


16 


IO.ACW 


Access File for Read/Write 


17 


10. ACE 


Access File for Read/Write/Extend 


20 


IO.DAC 


Deaccess File 


21 


IO.RVB 


Read Virtual Block 


22 


IO.WVB 


Write Virtual Block 


23 


IO. EXT 


Extend File 


24 


IO.CRE 


Create File 


25 


10. DEL 


Mark File for Delete 


26 


10, RAT 


Rpad Flip Affrihnfpt; 


27 


10. WAT 


Write File Attributes 


30 




Unused 


31 




Unused 


32 




Unused 


33 




Unused 


34 




Unused 


35 




Unused 


36 




Unused 


37 




Unused 
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Of the function code values listed in Table 3-1, only IO.KIL is 
mandatory and has a fixed interpretation. However, if 10. ATT and 
IO.DET are used, they must have the standard .meaning. If QIO 
directive processing encounters a function code of 3 or 4 and the code 
is not no-op'ed, it will assume that they represent Attach device and 
Detach device, respectively. The other codes are suggested but not 
mandatory. The driver writer is free to establish all other function 
code values on non-file-structured devices. The mask words must 
obviously reflect the proper filtering process. 

If a driver is being written for a file-structured device, the 
standard function codes of Table 3-1 must be used. 



3.1.3 The Status Control Block (SCB) 



Figure 3-4 is a layout of the 13-word SCB. The SCB describes the 
status of a control unit which can run in parallel with all other 
control units. 



S.LHD 

S.PRI 
S.VCT 
S.CTM 
S.ITM 
S.CON 
S.STS 

S.CSR 

S.PKT 

S.FRK 



DEVICE I/O QUEUE 


LISTHEAD 


VECTOR ADDR/4 


DEVICE PRIORITY 


INT TMOUT CNT 


CURNT TMOUT CNT 


CTRLR STATUS 


CONTROLLER #*2 


ADDRESS OF CONTROL STATUS REG 


ADDRESS OF CURRENT I/O PACKET 


FORK LINK WORD 


FORK PC 


FORK R5 


FORK R4 



Figure 3-4 
Status Control Block 
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3.1.3.1 SCB Details - The fields in the SCB are described below: 
S.LHD (first word equals zero; second word points to first) 
Driver access: 

Initialized, not referenced. 
Description: 

Two words which form the I/O queue listhead. The first word 
points to the first I/O Packet in the queue, and the second 
word points to the last I/O Packet in the queue. If the 
queue is empty, the first word is zero, and the second word 
points to the first word. 

S.PRI (device priority) 

Driver access: 

Initialized, not referenced. 

Description: 

Contains the priority at which the device interrupts. 

S.VCT (interrupt vector divided by four) 

Driver access: 

Initialized, not referenced. 

Description: 

Interrupt vector address divided by four. 

S.CTM (initialize to zero) 

Driver access: 

Not initialized, read/write. 

Descr iption : 

RSX-11M supports device timeout, which enables a driver to 
limit the time that elapses between the issuing of an I/O 
operation and its termination. The current timeout count (in 
seconds) is initialized by moving S . ITM (initial timeout 
count) into S.CTM. The Executive clock service will examine 
active times, decrement them and, if they reach 0, call the 
driver at its device timeout entry point. 

The internal clock count is kept in 1-second increments. 
Thus, a time count of 1 is not precise, since the internal 
clocking mechanism is operating asynchronously with driver 
execution. The only meaningful minimum clock interval is 2 
if the programmer intends to treat timeout as a consistent] y 
detectable error condition. Note, if the count is 0, thai no 
timeout will occur; it is, in fact, an indication that 
timeout is not operative. The maximum count is 255. The 
driver writer is responsible for setting this field. 
Resetting is at actual timeout or within $FORK. 



3-17 



WRITING AN I/O DRIVER - PROGRAMMING SPECIFICS 

S.ITM (set to initial timeout count) 

Driver access: 

Initialized, read-only. 

Description: 

Contains the initial timeout value. 

S.CON (controller number times 2) 

Driver access: 

Initialized, read-only. 

Description: 

Controller number multiplied by 2. Used by drivers which are 
written to support more than one controller. S.CON may be 
used by the driver to index into a controller table created 
and maintained internally to the driver itself. Indexing the 
controller table enables the driver to service the correct 

S.STS (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

Establishes the controller as busy/not busy. This byte is 
the interlock mechanism for marking a driver as busy for a 
specific controller. Tested and set by $GTPKT and reset by 
$IODON. 

S.CSR (Control Status Register address) 

Driver access: 

Initialized, read/only. 

Description: 

Contains the address of the Control Status Register (CSR) for 
the device controller. S.CSR is used by the driver to 
initiate I/O operations and to access, via indexing, other 
registers related to the device that are located in the I/O 
page. This address need not be a CSR; it need only be a 
member of the device's register set. It is accessed at 
system bootstrap time to determine if the interface exists on 
the system hosting the Executive. The Executive uses this to 
set the off-line bit at bootstrap so system software can be 
interchanged between systems without an intervening system 
generation. Otherwise, it is only accessed by the driver 
itself. 
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S.PKT (Reserve one word of storage) 

Driver access: 

Not initialized, read-only. 

Description: 

Address of the current I/O Packet established by $GTPKT. 
This field is used to retrieve the I/O Packet address upon 
the completion of an I/O request. 

S.FRK (reserve four words of storage) 

Driver access: 

\Ti~> +• iT-iit-isii 2^d no t re f e r enc ed 

Description: 

The four words starting at S.FRK are used for fork block 
storage if and when the driver deems it necessary to 
establish itself as a Fork process. Fork block storage 
preserves the state of the driver, which is restored when the 
driver regains control at fork level. This area is 
automatically used if the driver calls $FORK. 

3.1.4 The Unit Control Block (UCB) 



Figure 3-5 is a layout of the UCB (a variable-length control block) . 

One UCB exists for each physical device-unit generated into a system 

configuration. For user-added drivers, this control block is defined 
as part of the source code for the driver data structure. 
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U.DCB 

U.RED 
U.STS 
U.CTL 
U.ST2 
U.UNIT 

U.CW1 

U.CW2 

U.CW3 

U.CW4 

U.SCB 

U.ATT 

U.BUF 

U.BUF+2 

U.CNT 



BACK POINTER TO DCB 



REDIRECT UCB POINTER 



UNIT STATUS 



STATUS EXT 



CONTROL FLAGS 



PHYSICAL UNIT # 



CHARACTERISTICS WORD #1 



CHARACTERISTICS WORD #2 



CHARACTERISTICS WORD #3 



CHARACTERISTICS WORD #4 



POINTER TO SCB 



ICB ADDR OF ATTACHED TASK 



BUFFER RELOCATION BIAS 



BUFFER ADDRESS 



BYTE COUNT 



DEVICE 
DEPENDENT 



STORAGE 



Figure 3-5 
Unit Control Block 
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3.1.4.1 UCB Details - The fields in the UCB are described below: 

U.DCB (pointer to associated DCB) 

Driver access: 

Initialized, not referenced. 

Description: 

Backpointer to the corresponding DCB. Since the UCB is a key 
control block in the I/O data structure, access to other 
control blocks usually occurs via links implanted in the UCB. 

U RED (initialized to point to U.DCB of the UCB) 

Driver access: 

Initialized, not referenced. 

Description: 

Contains a pointer to the UCB to which this device unit has 
been redirected. This field is updated as the result of an 
MCR Redirect command. The redirect chain ends when this word 
points to the UCB itself. 

U.CTL (set by driver writer) 

Driver access: 

Initialized, not referenced. 

Description: 

U.CTL and the function mask words in the DCB drive QIO 
directive processing. The driver writer is totally 
responsible for setting up this bit pattern. Any inaccuracy 
in the bit setting of U.CTL will produce erroneous I/O 
processing. Bit symbols and their meaning are as follows: 

UC.ALG - Alignment bit. 

If this bit = 0, then byte alignment of data buffers is 
allowed. If UC.ALG = 1, then buffers must be word 
aligned . 

UC.ATT - Attach/Detach notification. 

If this bit is set, then the driver will be called when 
an Attach/Detach I/O function is processed by $GTPKT. 
Typically, the driver has no need to obtain control for 
Attach/Detach requests, and the Executive performs the 
entire function without any assistance from the driver. 

UC.KIL - Unconditional Cancel I/O call bit. 

If set, the driver is to be called on a Cancel I/O 

request, even if the unit specified is not busy. 

Typically, the driver is called on Cancel I/O only if an 
I/O operation is in progress. 
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UC.QUE - Queue bypass bit. 

If set, the QIO directive processor is to call the driver 
prior to queueing the I/O Packet. Once gaining 
to-be-queued control, the disposition of the I/O Packet 
is the driver's responsibility. Typically, an I/O Packet 
is queued prior to a call to the driver, which later 
retrieves it by a call to $GTPKT. 

UC.PWF - Unconditional call on power failure bit. 

If set, the driver is always to be called when power is 

restored after a power failure occurs. Typically, the 

driver is called on power restoration only when an I/O 
operation is in progress. 

UC.NPR - NPR device bit. 

If set, the device is an NPR device. This bit determines 
the format of the 2-word address in U.BUF (details given 
under the discussion of U.BUF below) . 

UC.LGH - Buffer size mask bits (2-bits). 

These two bits are used to check if the byte count 
specified in an I/O request is a legal buffer modulus. 

00 - Any buffer modulus valid 

01 - Must have word alignment modulus 

11 - Must have double word-alignment modulus 
10 - Combination invalid. 

UC.ALG and UC.LGH are independent settings. 

UC.ATT, UC.KIL, UC.QUE, and UC.PWF will usually be zero, 
especially for conventional drivers. 

Every driver must, however, be concerned with its particular 
values for UC.ALG, UC.NPR, and UC.LGH. 

The driver writer is totally responsible for the values in 
these bits, and erroneous values are likely to produce 
unpredictable results. 

U.STS (initialize to zero) 

Driver access: 

Initialized, not referenced. 

Description: 

This byte contains device-independent status information. 
The bit meanings are as follows: 

US.BSY - If set, device-unit is busy. 

US.MNT - If set, volume is not MOUnted. 
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US . FOR - If set, volume is foreign. 

US.MDM - If set, device is marked for dismount. 

The unused bits in U.STS are reserved for system use and 
expansion. US.MDM, US . MNT , and US . FOR apply only to 
MOUntable devices. 

U.UNIT (unit number) 

Driver access: 

Initialized, read-only. 

Descr iption: 

This byte contains the physical unit number of the 
device-unit. If the controller for the device supports only 
a single unit, the unit number is always zero. 

U.ST2 (set by driver writer) 

Driver access: 

Initialized, not referenced. 

Description: 

This byte contains additional device-independ«nt status 
information. The bit meanings are as follows: 

US.OFL - If set, the device is off-line (that is, not in 
the configuration) . 

US. RED - If set, the device cannot be redirected. 

The remaining bits are reserved for system use and expansion. 

U.CWl (set by driver writer) 

Driver access: 

Initialized, not referenced. 

Description : 

The first of a 4-word contiguous cluster of device 
characteristics information. U.CWl and U.CW4 are 

device-independent. U.CW2 and U.CW3 are device-dependent. 
The four characteristic words are retrieved from the UCB and 
placed in the requester's buffer on issuance of a GLUN$ 
Executive directive (Get LUN Information). It is the 
responsibility of the driver writer to supply the contents of 
these four words in the assembly source code of the driver 
data structure. 
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U.CWl is defined as follows: 

DV.REC Bit — Record-Oriented Device (l=yes) 
DV.CCL Bit 1 — Carriage-Control Device (l=yes) 
DV.TTY Bit 2 — Terminal Device (l=yes) 
DV.DIR Bit 3 — Directory Device (l=yes) 
DV.SDI Bit 4 — Single Directory Device (l=yes) 
DV.SQD Bit 5 — Sequential Device (l=yes) 
DV.PSE Bit 12 — Pseudo Device (l=yes) 
DV.COM Bit 13 — Device Mountable as a 

Communications Channel (l=yes) 
DV.Fll Bit 14 — Device mountable as a FILES-11 

device (l=Yes) 
DV.MNT Bit 15 — Device mountable (l=yes) 

U.CW2 (initialize to zero) 

Driver access: 

Initialized, read/write. 

Description: 

Specific to a given device driver (available for working 
storage or constants) . 

U.CW3 (initialize to zero) 

Driver access: 

Initialized, read/write. 

Descr iption: 

Specific to a given device driver (available for working 
storage or constants) . 

U.CW4 (set by driver writer) 

Driver access: 

Initialized, read-only. 

Description: 

Default buffer size. 

U.SCB (SCB pointer) 

Driver access: 

Initialized, read-only. 

Descr iption : 

This field contains a pointer to the SCB for this UCB. In 
general, R4 on entry to the driver via the driver dispatch 
table will contain the value in this word, since the SCB is 
frequently referenced by service routines. 
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U.ATT (initialize to zero) 
Driver access: 

Initialized, not referenced. 
Description: 

If a task has attached itself to a device-unit, this field 
contains its TCB address. 

U.BUF (reserve two words of storage) 

Driver access: 

Not initialized, read/write. 

Description: 

U.BUF labels two consecutive words which serve as a 
communication region between $GTPKT and the driver. If a 
non-transfer function is indicated, then U.BUF, U.BUF+2, and 
U.CNT receive the first three parameter words from the I/O 
Packet. 

For transfer operations, the format of these two words 
depends on the setting of UC.NPRin U.CTL. ^The^driver does 
not format the words; all formatting is completed prior to 
the driver receiving control. For unmapped systems, the 
first word is zero, and the second word is the physical 
address of the buffer. For mapped systems, the format is 
determined by the UC.NPR bit, which is set for an NPR device 
and reset for a program transfer device. 

Format for program transfer devices: 

The format is identical to that for the second two words of 
I.IOSB in the I/O Packet. See section 3.1.1.1. 

In general, the driver will not manipulate these words when 
performing I/O to program transfer device. It most likely 
will use the Executive routines Get Byte, Get Word, Put Byte, 
and Put Word to effect data transfers between the device and 
the user ' s buffer . 

Format for an NPR device: 

For NPR device drivers, the word layout is as follows: 

Word 1 

Bit Go bit initially set to zero 

Bit 1-3 Function code - set to zeros 

Bit 4,5 Memory extension bits 

Bit 6 Interrupt enable-set to zero 

Bits 7-15 Zero 

Word 2 

Bits 0-15 Low-order 16-bits of physical address 
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It is the driver's responsibility to set the function code, 
interrupt enable, and go bits. This must be accomplished by 
a Bit Set (BIS) operation so the extension bits are not 
disturbed. The driver is also responsible for moving these 
words into the device control registers to initiate the I/O 
operation. 

Note that when the system is unmapped, bits 4 and 5 will 
always be zero, but this is transparent to the driver. Thus, 
NPR device drivers will not be cognizant of the mapping state 

in the system. 

The construction of U.BUF, U.BUF+2 and U.CNT occurs only if 
the requested function is a transfer function; if it is not, 
these three words contain the first three words of the I/O 
Packet . 

The details of the construction of the Address Doubleword 
appear in Appendix A. 

U.CNT (reserve one word of storage) 

Driver access: 

Not initialized, read/write. 

Description : 

Contains the byte count of the buffer described by U.BUF. 
The driver will use this field in constructing the actual 
device request. 

U.BUF and U.CNT are used to keep track of the current data 
item in the buffer for the current transfer (except for NPR 
transfers) . Since this field is being altered dynamically, 
the I/O Packet may be needed to reissue an I/O operation. 

Device-Dependent Words: 

Driver access: 

Not initialized, read/write. 

Descr iption : 

The field is variable in length and is established by the 
driver writer to suit driver-specific requirements. 
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CHAPTER 4 
EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 



This section contains the Executive routines typically used by I/O 
drivers. They are listed in alphabetical order. The descriptions are 
taken directly from the code for the associated service. 



4.1 SYSTEM-STATE REGISTER CONVENTIONS 

In svstem state, R5 and R4 are, by convention, established as 
non-volatile registers. This means that an internally called routine 
is required to save and restore these two registers if it intends to 
destroy their contents. Note that drivers are entered directly from 
interrupts and have to call $INTSV to preserve R5 and R4. 

R3, R2, Rl, and RO are volatile registers and may be used by a called 
routine without save and restore responsibilities. 

A routine may violate these conventions, as long as an explicit 
statement exists in the program preface detailing the departure from 
conventions. Such departures should be avoided and employed only when 
ample justification 'can be given to demonstrate the value added to 
overall system performance by virtue of the proposed departure. 



4.2 SERVICE CALLS 
DEVICE MESSAGE OUTPUT 



$DVMSG 



Device Message Output is in the file IOSUB. 
Calling sequence: 
CALL $DVMSG 
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Descr ipt ion : 

+ 
**-SDVMSG-DEVICE MESSAGE OUTPUT 

THIS ROUTINE IS CALLED TO SUBMIT A MESSAGE TO THE TASK TERMINATION 
NOTIFICATION TASK. MESSAGES ARE EITHER DEVICE RELATED OR A CHECKPOINT 
WRITE FAILURE FROM THE LOADER. 



INPUTS: 



RO=MESSAGE NUMBER. 

R5=ADDRESS OF THE UCB OR TCB THAT THE MESSAGE APPLIES TO. 



OUTPUTS: 



Notes 



A FOUR WORD PACKET IS ALLOCATED, RO AND R5 ARE STORED IN THE 
SECOND AND THIRD WORDS, RESPECTIVELY, AND THE PACKET IS THREADED 
INTO THE TASK TERMINATION NOTIFICATION TASK MESSAGE QUEUE. 

NOTE: IF THE TASK TERMINATION NOTIFICATION TASK IS NOT INSTALLED 
OR NO STORAGE CAN BE OBTAINED, THEN THE MESSAGE REQUEST 
IS IGNORED. 



1. Drivers use only two codes in calling $DVMSG: T.NDNR (device 
not ready), and T.NDSE (select error). $DVMSG can be set up 
and called as follows: 

MOV #T.NDNR,R0 

or 

MOV #T.NDSE,R0 
CALL $DVMSG 
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l c;f?nDTf 



Fork is in the file SYSXT. $FORK is called by a driven to switch from 
a partially interr uptible level (its state following a call on $INTSV) 
to a fully interruptible level. 

Calling sequence: 

CALL $FORK 

Descr iption: 

+ 
**-$FORK-FORK AND CREATE SYSTEM PROCESS 

THIS ROUTINE IS CALLED FROM AN I/O DRIVER TO CREATE A SYSTEM PROCESS THAT 
WILL RETURN TO THE DRIVER AT STACK DEPTH ZERO TO FINISH PROCESSING. 

INPUTS: 

R5=ADDRESS OF THE UCB FOR THE UNIT BEING PROCESSED. 

OUTPUTS: 

REGISTERS R5 AND R4 ARE SAVED IN THE CONTROLLER FORK BLOCK AND 
A SYSTEM PROCESS IS CREATED. THE PROCESS IS LINKED TO THE FORK 
QUEUE AND A JUMP TO $INTXT IS EXECUTED. 



JOT! 



1. $FORK cannot be called unless $INTSV has been previously called. Tl 
fork processing routine assumes that entry conditions are set up 1 
$INTSV. 
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GET BYTE 



$GTBYT 



Get Byte is in the file BFCTL. 

Callinq sequence: 

CALL $GTBYT 

Descr iption : 

+ 
**-$GTBYT-GET NEXT BYTE FROM USER BUFFER 

THIS ROUTINE IS CALLED TO GET THE NEXT BYTE FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE BYTE HAS BEEN 
FETCHED, THE NEXT BYTE ADDRESS IS INCREMENTED. 

INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 

OUTPUTS: 

THE NEXT BYTE IS FETCHED FROM THE USER BUFFER AND RETURNED 

TO THE CALLER ON THE STACK. THE NEXT BYTE ADDRESS IS INCREMENTED 

ALL REGISTERS ARE PRESERVED ACROSS CALL, 
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GET PACKET 



$GTPKT 



Get Packet is in the file IOSUB. 

Calling sequence: 

CALL $GTPKT 

Description: 

+ 
**-$GTPKT-GET I/O PACKET FROM REQUEST QUEUE 

THIS ROUTINE IS CALLED BY DEVICE DRIVERS TO DEQUEUE THE NEXT I/O REQUEST 
PROCESS. IF THE DEVICE CONTROLLER IS BUSY, THEN A CARRY SET INDICATION I£ 
RETURNED TO THE CALLER. ELSE AN ATTEMPT IS MADE TO DEQUEUE THE NEXT REQUI 
FROM THE CONTROLLER QUEUE, IF NO REQUEST CAN BE DEQUEUED. THEN A CARRY 
SET INDICATION IS RETURNED TO THE CALLER. ELSE THE CONTROLLER IS SET BUS} 
A CARRY CLEAR INDICATION IS RETURNED TO THE CALLER. 

INPUTS: 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO GET A PACKET FOR. 

OUTPUTS: 

C=l IF CONTROLLER IS BUSY OR NO REQUEST CAN BE DEQUEUED. 
C=0 IF A REQUEST WAS SUCCESSFULLY DEQUEUED. 

R1=ADDRESS OF THE I/O PACKET. 

R2=PHYSICAL UNIT NUMBER. 

R3=CONTROLLER INDEX. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE UNIT CONTROL BLOCK. 

NOTE: R4 AND R5 ARE DESTROYED BY THIS ROUTINE. 
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GET WORD 



$GTWRD 



Get Word is in the file BFCTL, 

Calling sequence: 

Call $GTWRD 

Descr iption: 

+ 
**-$GTWRD-GET NEXT WORD FROM USER BUFFER 

THIS ROUTINE IS CALLED TO GET THE NEXT WORD FROM THE USER BUFFER 
AND RETURN IT TO THE CALLER ON THE STACK. AFTER THE WORD HAS BEEN 
FETCHED, THE NEXT WORD ADDRESS IS CALCULATED. 

INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 

OUTPUTS: 

THE NEXT WORD IS FETCHED FROM THE USER BUFFER AND RETURNED 

TO THE CALLER ON THE STACK. THE NEXT WORD ADDRESS IS CALCULATED 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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$INTSV 



INTERRUPT SAVE 

Interrupt Save is in the file SYSXT. 

Calling sequence: 

CALL $INTSV,PRn 

n has a range of 0-7. 

Description: 

+ 
**-$INTSV-INTERRUPT SAVE 

THIS ROUTINE IS CALLED FROM AN INTERRUPT SERVICE ROUTINE WHEN AN 
INTERRUPT IS NOT GOING TO BE IMMEDIATELY DISMISSED. A SWITCH TO 
THE SYSTEM STACK IS EXECUTED IF THE CURRENT STACK DEPTH IS +1. WHEN 
THE INTERRUPT SERVICE ROUTINE FINISHES ITS PROCESSING, IT EITHER FORKS 
OR JUMPS TO $INTXT. 



INPUTS: 



4(SP)=PS WORD PUSHED BY INTERRUPT. 
2(SP)=PC WORD PUSHED BY INTERRUPT. 
0(SP)=SAVED R5 PUSHED BY 'JSR R5,$INTSV. 
0(R5)=NEW PROCESSOR PRIORITY. 



OUTPUTS: 



REGISTER R4 IS PUSHED ONTO THE CURRENT STACK AND THE CURRENT 
STACK DEPTH IS DECREMENTED. IF THE RESULT IS ZERO, THEN 
A SWITCH TO THE SYSTEM STACK IS EXECUTED. THE NEW PROCESSOR 
STATUS IS LOADED AND A RETURN TO THE CALLER IS EXECUTED. 
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INTERRUPT EXIT 

Interrupt Exit is in the file SYSXT. 
Calling sequence: 
JMP $INTXT 
Descr iption: 



$INTXT 



**-$INTXT-INTERRUPT EXIT 

THIS ROUTINE IS CALLED VIA A JUMP TO EXIT FROM AN INTERRUPT. IF THE 

STACK DEPTH IS NOT EQUAL TO ZERO, THEN REGISTERS R4 AND R5 ARE 

RESTORED AND AN RTI IS EXECUTED. ELSE A CHECK IS MADE TO SEE 

IF THERE ARE ANY ENTRIES IN THE FORK QUEUE. IF NONE, THEN R4 AND 

R5 ARE RESTORED AND AN RTI IS EXECUTED. ELSE REGISTERS R3 THRU 

RO ARE SAVED ON THE CURRENT STACK AND A DIRECTIVE EXIT IS EXECUTED. 

INPUTS: (MAPPED SYSTEM) 

06(SP)=PS WORD PUSHED BY INTERRUPT. 
04(SP)=PC WORD PUSHED BY INTERRUPT. 
02 (SP)=SAVED R5. 
00 (SP)=SAVED R4. 

INPUTS: (REAL MEMORY SYSTEM) 

NONE. 
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$IODON 



EXECUTIVE SERVICES AVAILABLE TO I/O DRIVERS 
I/O ALTERNATE ENTRY and I/O DONE 

These routines are in the file IQSUB* 

Calling sequences: 

CALL $IOALT 

CALL $IODON 

Description: 

+ 
**-$IOALT-I/0 DONE (ALTERNATE ENTRY) 
**-$IODON-I/0 DONE 

mri-r^ nrtnmTMB TO n»Tr PTV 13 V T>TTi T TT r> C> PlOTWDDO R IT1 ITIttt? OAMnTPrjlTrtM PlD JU T / C\ OPrirlB 
illiD KUUI1WD J.O V>nXJllL;U Di u£i VJ.V1J univuivd f* x iuu w wilt liu i i vh v/j. rim -"-/'-' »uywi 

TO DO FINAL PROCESSING. THE UNIT AND CONTROLLER ARE SET IDLE AND $IOFIN IS 
ENTERED TO FINISH THE PROCESSING. 

INPUTS: 

R0=FIRST I/O STATUS WORD. 

R1=SEC0ND I/O STATUS WORD. 

R5=ADDRESS OF THE UNIT CONTROL BLOCK OF THE UNIT BEING COMPLETED. 

NOTE: IF ENTRY IS AT $IOALT,- THEN Rl IS CLEARED TO SIGNIFY THAT THE 
SECOND STATUS WORD IS ZERO, 

OUTPUTS: 

THE UNIT AND CONTROLLER ARE SET IDLE. 

R3=ADDRESS OF THE CURRENT I/O PACKET. 
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I/O FINISH 



$IOFIN 



I/O Finish is in the file IOSUB. Drivers rarely call I/O Finish, but 
they should be aware of the fact that this routine is executed when 
$IOALT or $IODON is called. 

Calling sequence: 

CALL $IOFIN 

Descr iption : 

+ 
**-$IOFIN-I/0 FINISH 

THIS ROUTINE IS CALLED TO FINISH I/O PROCESSING IN CASES WHERE THE UNIT AND 
CONTROLLER ARE NOT TO BE DECLARED IDLE. 

INPUTS: 

R0=FIRST I/O STATUS WORD. 
Rl=SECOND I/O STATUS WORD. 
R3=ADDRESS OF THE I/O REQUEST PACKET. 
R5=ADDRESS OF THE UNIT CONTROL BLOCK. 

OUTPUTS: 

THE FOLLOWING ACTIONS ARE PERFORMED: 

1-THE FINAL I/O STATUS VALUES ARE STORED IN THE I/O STATUS BLOCK IF 
ONE WAS SPECIFIED. 

2-THE I/O REQUEST COUNT IS DECREMENTED. IF THE RESULTANT COUNT IS 
ZERO, THEN ' TS . RDN ' IS CLEARED IN CASE THE TASK WAS 
STOPPED FOR I/O RUNDOWN. 

3-IF 'TS.CKR' IS SET, THEN IT IS CLEARED AND CHECKPOINTING OF THE 
TASK IS INITIATED. 

4-IF AN AST SERVICE ROUTINE WAS SPECIFIED, THEN AN AST IS QUEUED 
FOR THE TASK. ELSE THE I/O PACKET IS DEALLOCATED. 

5-A SIGNIFICANT EVENT OR EQUIVALENT IS DECLARED. 

NOTE: R4 IS DESTROYED BY THIS ROUTINE. 
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PUT BYTE 



$PTBYT 



Put Byte is in the file BFCTL. 

Calling sequence: 

CALL $PTBYT 

Description: 

+ 
**-$PTBYT-PUT NEXT BYTE IN USER BUFFER 

THIS ROUTINE IS CALLED TO PUT A BYTE IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE BYTE HAS BEEN STORED, THE NEXT BYTE ADDRESS 

IS INCREMENTED. 



INPUTS: 



R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=BYTE TO BE STORED IN THE NEXT LOCATION OF THE USER BUFFER, 



OUTPUTS: 



THE BYTE IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK. THE NEXT BYTE ADDRESS IS INCREMENTED. 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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PUT WORD 



$PTWRD 



Put Word is in the file BFCTL. 

Calling sequence: 

CALL $PTWRD 

Descr iption: 

+ 
**-$PTWRD-PUT NEXT WORD IN USER BUFFER 

THIS ROUTINE IS CALLED TO PUT A WORD IN THE NEXT LOCATION IN 

USER BUFFER. AFTER THE WORD HAS BEEN STORED, THE NEXT WORD ADDRESS 

IS CALCULATED. 

INPUTS: 

R5=ADDRESS OF THE UCB THAT CONTAINS THE BUFFER POINTERS. 
2(SP)=WORD TO BE STORED IN THE NEXT LOCATION OF THE BUFFER. 



OUTPUTS: 



THE WORD IS STORED IN THE USER BUFFER AND REMOVED FROM 
THE STACK. THE NEXT WORD ADDRESS IS CALCULATED. 

ALL REGISTERS ARE PRESERVED ACROSS CALL. 
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CHAPTER 5 
INCLUDING A USER-WRITTEN DRIVER - AN EXAMPLE 



The example which follows is a complete illustration of the procedures 
required to add a driver to an RSX-11M system. The driver in the 
example supports the punch capability of the PC11 Paper Tape 
Reader/Punch . 



5.1 DEVICE DESCRIPTION 



The PC11 Paper Tape Reader/Punch is capable of reading 8-hole, 
unoiled, perforated paper tape at 300 characters-per-second, and 
punching tape at 50 characters-per-second. The system consists of a 
Paper Tape Reader/Punch and Controller. A unit containing a reader 
only (PR11) is also available. 

In reading tape, a set of photodiodes translates the presence or 
absence of holes in the tape to logic levels representing l's and 0's. 
In punching tape, a mechanism translates logic levels representing l's 
and 0's to the presence or absence of holes in the tape. Any 
information read or punched is parallel-transferred through the 
Controller. When an address is placed on the UNIBUS, the Controller 
decodes the address and determines if the reader or punch has been 
selected. If one of the four device register addresses has been 
selected, the Controller determines whether an input or an output 
operation should be performed. An input operation from the reader is 

1*1 t- 1 ^t- n ^ T.iVi^r-. 4- V->^ -rw/^^aa.iS'^y 4-var>emi4-c a rinmrnanH f-n 1" h i= P^TIf^r Tfl Df* 

illl LIOLCU WliCU LUC ^LU^COOui. ti U11U1HJ.1.1J V* vuii.iii^w^ — ~ — » - w - w- £- ^- - £ 

Reader status register. An output operation is initiated when the 
processor transfers a byte to the Paper Tape Punch buffer register. 

The Controller enables the PDP-11 System to control the reading or 
punching of paper tape in a flexible manner. The reader can be 
operated independently of the punch; either device can be under 
direct program control or can operate without direct supervision, 
through the use of interrupts, to maintain continuous operation. 
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5.2 DATA STRUCTURE AND DRIVER SOURCE 

The simplicity of writing a conventional driver for RSX-11M is 
obscured by the volume of explanation required to cover the universal 
case. As will be seen below, in a particular case, building a 
conventional driver is indeed a straightforward and modest 
undertaking . 



5.2.1 The Data Structure 



The data structure source is shown below and is self-explanatory. 
Special note should be taken of the legal function mask words, 
starting at line 45. The standard function codes listed in Table 3-1 
were used in creating the mask. Thus, the Punch driver will accept 
the following I/O functions: 

Cancel I/O 

Write Logical Block 

Attach Device 

Detach Device 

Access File For Read/Write 

Access File For Read/Write/Extend 

Deaccess File 

Write Virtual Block 



Cancel I/O is Mandatory. Write Logical Block is the only transfer 
function actually supported. 

Attach/Detach are control functions. The two Access/Deaccess 
functions are legal for FCS compatibility, but are no-op'ed. Write 
Virtual Block is legal but will be converted to Write Logical Block by 
QIO directive processing. 

The Bit Mask for each function is as follows: 



FUNCTION 


FUNCTION 


CAN 





WLB 


1 


ATT 


3 


DET 


4 


ACW 


16 


ACE 


17 


DEA 


20 


WVB 


22 



CODE (OCTAL) MASK (OCTAL) BIT RANGE (DECIMAL) 



000001 


0-15. 


000002 


0-15. 


000010 


0-15. 


000020 


0-15. 


040000 


0-15. 


100000 


0-15. 


000001 


16.-31 


000004 


16.-31 



The legal masks result from adding the 0-15(10) bit-range words to 
form a mask and all the 16 (10) -31 (10) bit-range words to form the 
second mask. 

The Control, No-op, and ACP masks are created in an analogous fashion, 
matching bit positions with legal function code meanings. 
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The complete mask words appear on lines 45 thru 52 
structure source. 



in the data 



The function code selections for record-oriented devices are intended 
to match FCS requirements for file-structured devices. When FCS 
executes an Access For Write, it will simply be marked a no-op. This 
tends to minimize FCS device-dependent logic. 

Note also on line 84 that the controller number, which is encoded in 
the low byte of the interrupt vector PS word in RSX-11M, is set to 
zero . 



1 
2 
3 
4 
5 

6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 

C V 

30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 



.TITLE USRTB 
.IDENT /01/ 



COPYRIGHT 1975,- DIGITAL EQUIPMENT CORP.. MAYNARD, MASS. 

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

VERSION 01 

J. PASCUSNIK 25-NOV-74 

CONTROL BLOCKS FOR PAPER TAPE PUNCH DRIVER 

MACRO LIBRARY CALLS 



.MCALL DEVDF$,HWDDF$ 

iju vjur >p 

HWDDF$ 



•DEFINE DEVICE CONTROL BLOCK OFFSETS* 
;DEFINE HARDWARE REGISTERS 



PAPER TAPE PUNCH DEVICE DATA BASE 
PAPER TAPE PUNCH DEVICE CONTROL BLOCK 



$USRTB: : 
PPDCB: 



.WORD 

,WORD .PP0 

.ASCII /PP/ 

.BYTE 0,0 

.WORD PPND-PPST 

.WORD $PPTBL 

.WORD 140033 



LINK TO NEXT DCB 

POINTER TO FIRST UCB 

DEVICE NAME 

LOWEST AND HIGHEST UNIT NUMBERS COVE 

BY THIS DCB 
LENGTH OF EACH UCB IN BYTES 
POINTER TO DRIVER DISPATCH TABLE 
LEGAL FUNCTION MASK CODES 0-15. 



* Appendix B lists all macros which exist in RSX-11M and generate control 
offsets . 
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46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
90 

91 

32 
93 
94 
95 
96 
97 
98 
99 
00 



WORD 


30 


WORD 


140000 


WORD 





WORD 


5 


WORD 





WORD 


1 


WORD 


4 



CONTROL FUNCTION MASK CODES 0-15. 
NO-P'ED FUNCTION MASK CODES 0-15. 
ACP FUNCTION MASK CODES 0-15. 
LEGAL FUNCTION MASK CODES 16.-31. 
CONTROL FUNCTION MASK CODES 16.-31. 
NO-OP' ED FUNCTION MASK CODES 16.-31 
ACP FUNCTION MASK CODES 16.-31. 



PAPER TAPE PUNCH UNIT CONTROL BLOCK 



.PP0; 
PPST= 



WORD 
WORD 
BYTE 


PPDCB 

.-2 

UC.ATT,0 


BYTE 
WORD 


0,0 
DV.REC 


WORD 





WORD 





WORD 


64. 


WORD 
WORD 
BLKW 


PPSCB 


1 


BLKW 
BLKW 


1 
1 



BACK POINTER TO DCB 

POINTER TO REDIRECT UNIT UCB 

CONTROL PROCESSING FLAG (PASS CONTROL 

ON ATTACH/DETACH) , UNIT STATUS 
PHYSICAL UNIT NUMBER, UNIT STATUS EXTENSION 
FIRST DEVICE CHARACTERISTICS WORD 

(RECORD-ORIENTED DEVICE) 
SECOND DEVICE CHARACTERISTICS WORD 

(FOR INTERNAL USE BY DRIVER) 
THIRD DEVICE CHARACTERISTICS WORD 

(FOR INTERNAL USE BY DRIVER) 
FOURTH DEVICE CHARACTERISTICS WORD 

(DEFAULT BUFFER SIZE IN BYTES) 
POINTER TO SCB 

TCB ADDRESS OF ATTACHED TASK 
RELOCATION BIAS OF BUFFER OF CURRENT 

I/O REQUEST 
ADDRESS OF BUFFER OF CURRENT I/O REQUEST 
BYTE COUNT OF CURRENT I/O REQUEST 



PPND= 



PAPER TAPE PUNCH INTERRUPT VECTOR 



= 74 



.ASECT 

• WORD 
.WORD 
.PSECT 



$PPINT 
PR7I0 



;ADDRESS OF INTERRUPT ROUTINE 

; INTERRUPT AT PRIORITY 7 (CONTROLLERS ) 



PAPER TAPE PUNCH STATUS CONTROL BLOCK 



PPSCB: 



,WORD 

.WORD 
.BYTE 
.BYTE 
.BYTE 

.WORD 
.BLKW 
, BLKW 

, END 





.-2 

PR4,74/4 
0,4 
0,0 

177554 

1 

4 



CONTROLLER I/O QUEUE LISTHEAD 

(POINTER TO FIRST ENTRY) 

(POINTER TO LAST ENTRY) 
DEVICE PRI, INTERRUPT VECTOR ADDRESS/4 
CURRENT AND INITIAL TIMEOUT COUNTS 
CONTROLLER INDEX AND STATUS 

(0=IDLE, 1=BUSY) 
ADDRESS OF CONTROL STATUS REGISTER 
ADDRESS OF CURRENT I/O PACKET 
FORK BLOCK ALLOCATION 
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5.2.2 Driver Code 

The code shown below for the punch capability of the PC11 is typical 
for a conventional driver. In fact, many of the descriptive comments 
can be used as a template and easily tailored to a driver for another 
device. A few preliminary comments will simplify the examination of 
the code itself. 

Since the PP driver is a DEC product and will eventually be part of a 
released system, conditional ized sections in the code exist that will 
be included or deleted based on answers provided by the user to the 
configuration queries posed during system generation. The system 
generation questions determine the value of a symbol defined in the 
assembly prefix file RSXMC.MAC, The conditional ized sections of code 
are then controlled by the value of the symbol. The conditional ized 
code appears in multi-controller drivers and is recommended for all 

Conditional ized code for PP is implemented as follows: 

P$$P11 is set to the number of controllers the driver is to service. 
This sets the size of CNTBL and conditionally creates 'TEMP 1 , if 
P$$P11 >1. Also, if P$$P11 >1, code is generated to save PS in TEMP 
for retrieval on return from $INTSV, and the controller number is 
decoded from the low-order four bits of the saved PS and used to index 
into CNTBL to obtain the UCB address. For P$$Pll=l, CNTBL is one word 
long, TEMP is not necessary, and the UCB address is always the first 
entry in CNTBL. 

The structure of the driver follows the classic RSX-11M form being 
separated into processing code for: 

Initiator ; 

Power Failure; 

Interrupt; 

Timeout, and 



The driver itself services only Write Logical, Attach and Detach I/O 
functions. Attach and Detach result in the punching of 170(10) nulls 
each for header and trailer. 

Power Failure and Cancel I/O are handled via device timeout, as is the 
device-not-ready condition. 

The PP driver uses the following Executive services: 

$INTSV 
$INTXT 
$GTPKT 
$GTBYT 
$DVMSG 

Comments beginning with ';;;' indicate the instruction is being 
executed at a priority level greater than or equal to 4. 
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The code contained in lines 128-130 is used to inhibit the punching of 
a trailer on ATT/DET if the task is being aborted. This is especially 
desirable when the device is not ready (i.e., out of paper - tape) and 
the system has generated the detach for the aborting process. 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
1 8 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
5 6 



.TITLE PPDRV 
. IDENT /01/ 



COPYRIGHT 1975, DIGITAL EQUIPMENT CORP., MAYNARD, MASS. 01754 

THIS SOFTWARE IS FURNISHED TO PURCHASER UNDER A LICENSE FOR USE 
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH INCLUSION 
OF DEC'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH SYSTEM, EXCEPT 
AS MAY OTHERWISE BE PROVIDED IN WRITING BY DEC. 

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY 
OF ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 

VERSION 01 

J. PASCUSNIK 25-NOV-74 

PC11 PAPER TAPE PUNCH DRIVER 

MACRO LIBRARY CALLS 

. MCALL ABODF$ , DEVDF$ , HWDDF$ , PKTDF$ , TCBDF$ 



ABODF$ 
DEVDF$ 
HWDDF$ 
PKTDF$ 
TCBDF$ 



DEFINE TASK ABORT CODES 

DEFINE DEVICE CONTROL BLOCK OFFSETS 

DEFINE HARDWARE REGISTER SYMBOLS 

DEFINE I/O PACKET OFFSETS 

DEFINE TASK CONTROL BLOCK OFFSETS 



EQUATED SYMBOLS 

PAPER TAPE PUNCH STATUS WORD BIT DEFINITIONS (U.CW2) 



WAIT=100000 
ABORT=40000 
TRAIL=200 



WAITING FOR DEVICE TO COME ON-LINE (1=YES 
ABORT CURRENT I/O REQUEST (1=YES) 
CURRENTLY PUNCHING TRAILER (1=YES) 



LOCAL DATA 

CONTROLLER IMPURE DATA TABLES (INDEXED BY CONTROLLER NUMBER) 



CNTBL: . BLKW P$$P11 

.IF GT P$$P11-1 

TEMP: .BLKW 1 



; ADDRESS OF UNIT CONTROL BLOCK 



; TEMPORARY STORAGE FOR CONTROLLER NUMBER 
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57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 

84 
85 
86 
87 



.IFTF 



DRIVER DISPATCH TABLE 



$PPTBL: : 



,WORD 
.WORD 
■ WORD 
.WORD 



PPINI 
PPCAN 
PPOUT 
PPPWF 



DEVICE INITIATOR ENTRY POINT 
CANCEL I/O OPERATION ENTRY POINT 
DEVICE TIMEOUT ENTRY POINT 
POWERFAIL ENTRY POINT 



**-PPINI-PCll PAPER TAPE PUNCH CONTROLLER INITIATOR 

THIS ROUTINE IS ENTERED FROM THE QUEUE I/O DIRECTIVE WHEN AN I/O REQUEST 

^r, />r,nT,nn mm * m m u x? c vi rv OP A DDPUTnilC T/D nPFBaTTflN TO PROPAQATR THF, EXECU 

TION OF THE DRIVER. IF THE SPECIFIED CONTROLLER IS NOT BUSY, THEN AN ATTEMP 
IS MADE TO DEQUEUE THE NEXT I/O REQUEST. ELSE A RETURN TO THE CALLER IS 
EXECUTED. IF THE DEQUEUE ATTEMPT IS SUCCESSFUL, THEN THE NEXT I/O OPER- 
ATION IS INITIATED. A RETURN TO THE CALLER IS THEN EXECUTED. 



INPUTS: 



R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 



nriTwiT? 



IF THE SPECIFIED CONTROLLER IS NOT BUSY AND AN I/O REQUEST IS WAIT- 
ING TO BE PROCESSED, THEN THE REQUEST IS DEQUEUED AND THE I/O OPER- 
ATION IS INITIATED. 



89 

90 

91 

92 

93 

94 

95 

96 

97 

98 

99 

100 

101 

102 

103 

104 

105 

106 

107 

108 

109 

110 

111 

112 

113 

114 

115 

116 

117 



.ENABL LSB 
PPINI: CALL $GTPKT 

BCS PPPWF 



;GET AN I/O PACKET TO PROCESS 

;IF CS CONTROLLER BUSY OR NO REQUEST 



THE FOLLOWING ARGUMENTS APE RETURNED BY $GTPKT: 

r^ t -r ^* t-x t^ i-i /-i *-i r\r-\ mnn -r / r\ Tirrr^iiTPt 
KX = HJJJJKCDD ur ±nc J./ w nbyuLj. 

R2=PHYSICAL UNIT NUMBER OF THE REQUEST UCB. 

R3=CONTROLLER INDEX. 

R4=ADDRESS OF THE STATUS CONTROL BLOCK. 

R5=ADDRESS OF THE UCB OF THE CONTROLLER TO BE INITIATED. 

PAPER TAPE PUNCH I/O REQUEST PACKET FORMAT: 

I/O QUEUE THREAD WORD. 

REQUEST PRIORITY, EVENT FLAG NUMBER. 
ADDRESS OF THE TCB OF THE REQUESTER TASK. 
POINTER TO SECOND LUN WORD IN REQUESTER TASK HEADER. 
CONTENTS OF THE FIRST LUN WORD IN REQUESTER TASK HEADER (I" 
I/O FUNCTION CODE (IO.WLB, IO. ATT OR IO.DET). 
VIRTUAL ADDRESS OF I/O STATUS BLOCK. 
RELOCATION BIAS OF I/O STATUS BLOCK. 

I/O STATUS BLOCK ADDRESS (REAL OR DISPLACEMENT + 140000). 
VIRTUAL ADDRESS OF AST SERVICE ROUTINE. 
RELOCATION BIAS OF I/O BUFFER. 
BUFFER ADDRESS OF I/O TRANSFER. 
WD. 14 — NUMBER OF BYTES TO BE TRANSFERRED. 



WD. 


00 - 


WD. 


01 - 


WD. 


02 - 


WD. 


03 - 


WD. 


04 - 


WD. 


05 - 


WD. 


06 - 


WD. 


07 - 


WD. 


10 - 


WD. 


11 - 


WD. 


12 - 


WD. 


13 - 
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118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
173 
174 
175 
176 
177 
178 



WD. 15 - 

WD. 16 - 

WD. 17 - 

WD. 20 - 



- NOT USED, 

- NOT USED, 

- NOT USED, 

- NOT USED, 



10$: 
20$: 



MOV R5,CNTBL(R3) 

CLR U.CW2(R5) 

CMPB I.FCN+1 (Rl) ,#IO 

BEQ 10$ 

MOV I.TCB(Rl) ,R0 

BITB #TS.ABO,T.STAT+ 

BNE 65$ 

BIS #TRAIL,U.CW2(R5 

MOV #170. ,U.CNT(R5) 

BIS #WAIT,U.CW2(R5) 

TST @S.CSR(R4) 

BMI 80$ 

BIC #WAIT,U.CW2(R5) 

MOVB S. ITM(R4) f S.CTM 

MOV #100,@S.CSR(R4) 



;SAVE UCB POINTER FOR INTERRUPT ROUTINE 
; CLEAR ALL SWITCHES 
.WLB/256. ;WRITE LOGICAL BLOCK FUNCTION? 
;IF EQ YES 

;GET REQUESTER TCB ADDRESS 
2(R0) ;TASK BEING ABORTED? 

;IF NE YES - DON'T PUNCH TRAILER 
) ;OTHERWISE FUNCTION IS ATTACH OR DETACH 
SET FLAG TO PUNCH TRAILER 
SET COUNT FOR 170 NULLS 
ASSUME WAIT FOR DEVICE OFF LINE 
DEVICE OFF LINE? 
IF MI YES 

DEVICE ON LINE, CLEAR WAIT CONDITION 
(R4) ;SET TIMEOUT COUNT 
; ENABLE INTERRUPTS 



POWERFAIL IS HANDLED VIA THE DEVICE TIMEOUT FACILITY AND THEREFORE CAUSES 
NO IMMEDIATE ACTION ON THE DEVICE. THIS IS DONE TO AVOID A RACE CONDITIO* 
THAT COULD EXIST IN RESTARTING THE I/O OPERATION 



PPPWF: RETURN 
; + 



: -$PPINT-PCll PAPER TAPE PUNCH CONTROLLER INTERRUPTS 



$PPINT: : 



.IFT 

MOV PS, TEMP 

. IFTF 

CALL $INTSV,PR4 

. IFT 



MOV 
BIC 
ASL 
MOV 


TEMP,R4 
#177760, R4 
R4 
CNTBL(R4) ,R5 


. IFF 




MOV 


CNTBL,R5 


.ENDC 




MOV 
MOVB 


U.SCB(R5) ,R4 
S. ITM(R4) ,S. 



;;;REF LABEL 



;;;SAVE CONTROLLER NUMBER 



;;;SAVE REGISTERS AND SET PRIORITY 



; RETRIEVE CONTROLLER NUMBER 
; CLEAR ALL BUT CONTROLLER NUMBER 
; CONVERT TO CONTROLLER INDEX 
; RETRIEVE ADDRESS OF UCB 



;;; RETRIEVE ADDRESS OF UCB 



;;;GET ADDRESS OF STATUS CONTROL BLOCK 
R4) ;;; RESET TIMEOUT COUNT 
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179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 



30$ 

40$ 
50$ 
60$ 



65$ 
70$ 



MOV S.CSR{R4) ,R4 

MOV (R4)+,U.CW3(R5) 

BMI 60$ 

SUB #1,U.CNT(R5) 

BCS 50$ 

TSTB U.CW2(R5) 

BPL 30$ 

CLRB (R4) 

BR 40$ 

CALL $GTBYT 

MOVB (SP)+,(R4) 

JMP $INTXT 

INC U.CNT(R5) 

CLR -(R4) 

CALL $FORK 

MOV U.SCB(R5) ,R4 

MOV S:PKT (R4) - Rl 

MOV I.PRM+4(Ri) ,R1 

SUB U.CNT(R5) ,R1 

MOV #IS.SUC&377,R0 

TST U.CW3(R5) 

BPL 70$ 

MOV #IE.VER&377,R0 

CALL $IODON 

BR PPINI 



POINT R4 TO CONTROL STATUS REGISTER 

SAVE STATUS 

IF MI, ERROR 

DECREMENT CHARACTER COUNT 

IF CS, THEN DONE 

CURRENTLY PUNCHING TRAILER? 

IF PL NO 

PUNCH A NULL 

BRANCH TO EXIT FROM INTERRUPT 

GET NEXT BYTE FROM USER BUFFER 

LOAD BYTE IN OUTPUT REGISTER 

EXIT FROM INTERRUPT 

RESET BYTE COUNT 

DISABLE PUNCH INTERRUPTS 

CREATE SYSTEM PROCESS 
POINT R4 TO SCB 
POINT Rl TO I/O PACKET 

AND PICK UP CHARACTER COUNT 
CALCULATE CHARACTERS TRANSFERRED 
ASSUME SUCCESSFUL TRANSFER 
DEVICE ERROR? 
IF PL NO 

UNRECOVERABLE HARDWARE ERROR CODE 
INITIATE I/O COMPLETION 
BRANCH BACK FOR NEXT REQUEST 



DEVICE TIMEOUT RESULTS IN A NOT READY MESSAGE BEING PUT OUT 4 TIMES A 
MINUTE. TIMEOUTS ARE CAUSED BY POWERFAILURE AND PUNCH FAULT CONDITION 



PPOUT: CLRB @S.CSR(R4) 

CLRB PS 

80$: MOV #IE.DNR&377,R0 

MOV U.CW2(R5) ,R1 

BPL 70$ 

MOV #IE.ABO&377,R0 

ASL Rl 

BMI 70$ 

TST @S.CSR(R4) 

ddt one: 

u> J. j-i £» \j v 

MOV #T.NDNR,R0 

MOVB #1,S.CTM(R4) 

DECB S.STS(R4) 

BNE PPPWF 

MOVB #15. ,S.STS(R4) 

CALLR $DVMSG 

.DSABL LSB 



;;DISABLE PUNCH INTERRUPT 

;; ALLOW INTERRUPTS 

ASSUME DEVICE NOT READY ERROR 

ARE WE WAITING FOR DEVICE READY? 

IF PL NO, TERMINATE I/O REQUEST 

ASSUME REQUEST IS TO BE ABORTED 

ABORT REQUEST? 

IF MI YES 

PUNCH READY? 

IF PL YES 

SET FOR NOT READY MESSAGE 

SET TIMEOUT FOR 1 SECOND 

TIME TO OUTPUT MESSAGE? 

IF NE NO 

SET TO OUTPUT NEXT MESSAGE IN 15, 

OUTPUT MESSAGE 



SEC 



CANCEL I/O OPERATION-FORCE I/O TO COMPLETE IF DEVICE IS NOT READY 



PPCAN: CMP R1,I.TCB(R0) 

BNE 10$ 

BIS #ABORT,U.CW2 (R5) 
10$: RETURN 

.END 



REQUEST FOR CURRENT TASK? 

IF NE NO 

SET FOR ABORT IF DEVICE NOT READY 
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APPENDIX A 
DEVELOPMENT OF THE ADDRESS DOUBLEWORD 



A. 1 INTRODUCTION 

RSX-11M can be generated as a mapped or an unmapped system. Mapped 
systems can accommodate configurations whose maximum physical memory 
is 248K bytes. Individual tasks, however, are limited to 64K bytes. 
The addressing in a mapped system is accomplished by using virtual 
addresses and memory mapping hardware. I/O transfers, however, use 
physical addresses 18 bits in length. Since the PDP-11 word size is 
16 bits, some scheme was necessary for internal representation of an 
s^rJrgss until it was actually used in an I/O operation. 




The choice was made to encode two words as the internal representation 
^•p -, nh V c;i'o=i a^^rocc anri fn t- r an « f<~> r m virtual addresses for I/O 
operations into the internal doubleword format. 



A. 2 CREATING THE ADDRESS DOUBLEWORD 

For unmapped systems, the doubleword is simply a word of zeros 
followed by a word containing the real address. 

On receipt of a 010 directive for mapped systems, the buffer address 
in the DPB, which contains a task virtual address, is converted to 
address doubleword format. 

The virtual address in the DPB is structured as follows: 

Bits 0-5 Displacement in 32-word block 

Bits 6-12 Block number 

Eits 13-15 Page Address Register Number (PAR#) 
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DEVELOPMENT OF THE ADDRESS DOUBLEWORD 

The internal RSX-11M translation restructures this virtual address 
into an address doubleword as follows: 

The relocation base contained in the PAR specified by the PAR# in the 
virtual address in the DPB is added to the block number in the virtual 
address. This result becomes the first word of the address 
doubleword. It represents the nth 32-word block in a memory viewed as 
a collection of 32-word blocks. Note, that at the time the address 
doubleword is computed, the user issuing the CIO directive is mapped 
into the processor's memory management registers. 

The second word is formed by placing the displacement in block (bits 
0-5 of virtual address) into bits 0-5. The block number field was 
accommodated in the first word and bits 6-12 are cleared. Finally, a 
six is placed in bits 13-15 to enable use of PAR #6, which will be 
used by the Executive to service I/O for program transfer devices. 

For non-program transfer (NPR) devices, the driver requirements for 
manipulating the address doubleword are direct and are discussed with 
the description of U.BUF in section 3.1.4.1. 
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APPENDIX B 
SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.MACRO ABQDFS,L*B 



1 TASK ABORT CODES 





,CFLT 


»■ 




S.COAOs'B'fc, 




S,CSGF='B'2. 




S,CBPT=*B'a, 




S,CICT='B'fc, 




S,CILI='B'6. 




S.CE*Ts'B'H. 




S.CTRPs'BM2. 




S s CFLTs'B'l«* 




S,CSSTa»8'16. 




S.CAST='B'1«. 




S,CAB0='S'2w. 




S,CLRF='?'22. 




S.CCRFs'6'24. 




S.I0MG='8 # 2fe. 




S,PRTY='B'25. 





S-CFLT ARE ALSO SST VECTOR OFFSETS 



jQDD ADDRESS AND TRAPS TO 4 

, SEGMENT FAULT 

fBREAK POINT OP TRACE TRAP 

flOT INSTRUCTION 

jILLEGAL OR RESERVED INSTRUCTION 

jNON RSX EMT INSTRUCTION 

jTRAP INSTRUCTION 

tll/«0 FLOATING POINT EXCEPTION 

iSST ABORT-BAD STACK 

I AST ABORT-BAD STACK 

fABORT VIA DIRECTIVE 

,TASK LOAD REQUEST FAILURE 

fTASK CHECKPOINT READ FAILURE 

|TASK EXIT WITH OUTSTANDING I/O 

fTASK MEMORY PARITY ERROR 



1 TASK TERMINATION NOTIFICATION MESSAGE CODES 



T.NDNRa'B'? 

T,NCWFa'B'4 
T.NCREs'B'6 
T.ND^Os'B'6. 

T,NLDNs*BM2. 
T.^LUPs'B'n. 

, * A C R 

,E^D* 

,ENOM 



ABODF$ 



fDEVICE NOT READY 
■DEVICE SELECT ERROR 
ICHECKPOINT WRITE FAILURE 
fCARD READER HARDWARE ERROR 
^DISMOUNT COMPLETE 
f LINK DOW*» (NETWORKS) 
»LINK UP (NETWORKS) 



.MACRO CLKDF$,L,B 



CLOCK QUEUE CONTROL BLOCK OFFSET DEFINITIONS 
CLOCK QUEUE CONTROL BLOCK 

T HERF ARE FIVE TYPES OF CLOCK QUEUE CONTROL BLOCKS, EACH CONTROL BLOCK HAS 
THE SAME FORMAT IN THE FIRST FIVE WORDS AND DIFFERS IN THE REMAINING THREE 

THE FOLLOWING CONTROL BLOCK TYPES ARE DEFINED: 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



,MRKTs*B # 
,SCHDs'B'2 
,SSHT='B'4 
.SYSTs'B'fc 
.SYTKs'B'8. 



jMARK TIME REQUEST 

jTASK REQUEST with PERIODIC RESCHEDULING 

fSINGLE SHOT TASK REQUEST 

jSINGLE SHCT INTERNAL SYSTE M SUBROUTINE (IDENT) 

jSInGLE SHOT INTERNAL SYSTE* SUBROUTINE (TASK) 



CLOCK QUEUE CONTROL BLOCK TYPE INDEPENDENT OFFSET DEFINTIONS 



.ASECT 
= 

,LNK|'L' .BLKW 1 

.RQTi'L' .BLKB 1 

.EFNj'L' ,BLKB 1 

,TC8i'L' .9LK4 i 

.TIMj'L' .BLKW 2 



fCLOCK QUEUE THREAD WORD 

^REQUEST TYPE 

jEVEK'T FLAG n u m BER (*ARK TIME ONLY) 

f TCB ADDRE'SS OP SYSTEM SUBROUTINE IDENTIFICATION 

fABSOLUTE TI M E WHEN REQUEST CO^ES DUE 



CLOCK QUEUE CONTROL BLOCK-MARK TIME DEPENDENT OFFSET DEFINITIONS 



sC.TIH+4 

,A8Ti'L' .BLKW 1 

i S R C ! ' L * . B L K Ui 1 

IdsTi'L' isLKw I 



fSTART OF DEPENDENT AREA 

tAST ADDRESS 

■FLAG MASK WORD FOP 'BIS' SOURCE 

fADDRESS OF 'BIS' DESTINATION 



CLOCK QUEUE CONTROL BLOCK-PERIODIC RESCHEDULING DEPENDENT OFFSET DEFINITIONS 



sC.TIH + 4| 

.RSIl'L' .BLKW 2 
.UICi'L' .BLK* l 



fSTART OF DEPENDENT aRFa 
fRESCHEDULE INTERVAL IN CLOCK TICKS 
fSCHEDULING UIC 



CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT DEPENDENT OFFSET DEFINITIONS 



*C,TI*+4 

.BLKL- 2 
,3LK* 1 



fSTART OF DEPENDENT AREA 
I TWO UNUSED WORDS 
^SCHEDULING UIC 



CLOCK QUEUE CONTROL BLOCK-SINGLE SHOT INTERNAL SUBROUTINE OFFSET DEFINITIONS 

THERE ARE T*0 TYPE CODES FOR THIS TY D E OF REOUESTj'L' 

TYPE 6sSINGLE SHOT INTERNAL SUBROUTINE aIT* a 16 SIT VALUE AS AN IDENTIFIER, 
TY°E BbSINGLE SHOT INTERNAL SUBROUTINE *ITH A TCP ADDRESS AS A* IDENTIFIER, 



sC,TI*+4 

,SU6»'L' .BLKw i 
.BLK' 1 2 
,LGTH='»', 

.PSECT 



,«ACRC CLKDFS 

,END^ 



fSTART OF DEPENDENT AREA 

■SUBROUTINE ADDRESS 

I TWO UNUSED *0ROS 

ILE^GTH OF CLOCK QUEUE CONTROL BLOCK 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



.MACRO DCBDF$,L,B 



DEVICE CONTROL BLOCK 

THE DEVICE CONTROL. BLOCK (DCB) DEFINES GENERIC INFORMATION ABOUT A DEVICE 
TYPE AND THE LOWEST AND HIGHEST UNIT NUMBERS, THERE IS AT LEAST ONE DCB 
FOR EACH DEVICE TYPE IN A SYSTEM, FOR EXAMPLE, IF THERE ARE TELETYPES IN A 
SYSTEM, THEN THERE IS AT LEAST ONE DCB WITH THE DEVICE NAME 'TT'. IF PART 
OF THE TELETYPES WERE INTERFACED VIA DLll-A'S AND THE REST VIA A DHU, THE 
THERE WOULD BE TWO DCB'S, ONE FOR ALL DLll-A INTERFACED TELETYPES, AND ONE 
FOR ALL D*ll INTERFACED TELETYPES, A SIMILAR SITUATION WOULD ARISE IF A 
SYSTEM CONTAINED TWO RK11 DISK CONTROLLERS, ONE DCB WOULD BE REQUIRED 
FOR EACH CONTROLLER, 



.ASECT 

D.LNKI'L' ,SLK* 
D.UCBl'L' .BLKW 
D.NAMf'L' ,3LKW 
D.UNITl'L' .6LKB 

RL K fi 
D.UCBLJ'L' .BLKw 
D,DSP| # L* .BLKw 
D,MSKi*L* ,3LKW 
.BLKW 
,8LKW 
,8LK* 
.BLKW 
a i * i,. 

,8L<W 
• BLKW 



LINK TO NEXT DCB 

POINTER TO FIRST UNIT CONTROL BLOCK 

GENERIC DEVICE WA*E 

LOWEST UNIT NUMBER COVERED BY THIS DCB 

HIGHEST UNIT NUMBER COVERED BY THIS DCB 

LENGTH OF EACH UNIT CONTROL BLOCK IN BYTES 

POINTER TO DRIVER DISPATCH TABLE 

LEGAL FUNCTION MASK CODES 0-15, 

CONTROL FUNCTION MASK CODES 2-15, 

NOP'ED FUNCTION MASK CODES 5?- 15. 

ACP FUNCTION MASK CODES 2-15. 

LEGAL FUNCTION MASK CODES 16,-31, 

rn m t d n i_ PijMrTTns M A S K CODES 16.-31. 

NOP'Ed'fuNCTICN MASK CODES 16.-31," 

ACP FUNCTION MASK CODES 16,-31, 



.PSECT 

I* 

I DRIVER DISPATCH TABLE OFFSET DEFINITIONS 

I- 



D.VINIs'B'8 
D,VCAN='8'2 

D.VOUTs'BM 
D.VPWFs'B'6 



.MACRO DCBDFS,X,Y 

,EnDm 
,ENDM 



jDEVICE INITIATOR 

iCANCEL CURRENT I/O FUNCTION 

»DEVICE TIMEOUT 

iPOWERFAIL RECOVERY 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



,*ACP0 FUDFS 



t VOLUME 


CONTROL 


1 


.ASECT 


• «0 




V.TRCT: 


, B L K * 1 


V.IFWIi 


,RLKW 1 


V.FCBr 


,*LK* 2 


V.IBLBj , 


,BLK8 1 


V.IBSZl , 


,BLKB 1 




, 8 L K a 1 


V.FMAXl ! 


, BL*.' j 1 


V.WISZ: , 


,BLKB 1 


V.SBCL: , 


,BLKB 1 


v.sesz: 


,SLKw 1 


V.SBLBt , 


,BLKB 1 


V.FIEXs , 


, BLKB 1 




, B L K '" 1 


V.VOWNi 


, B L K * 1 


V.VPROi 


, B L K * 1 


V.VCHA: , 


, B L K w 1 


V.FPRQf , 


, B L * il 1 


V.VFSQ: , 


,BLK* 1 


V,FRB*t , 


s RL<« J 


V.LRUCt , 


,BL<e i 




, R L K v i 



V.UGTHi 



^TRANSACTION COUNT 






fINDEX FILE WINDOW 






fFILE CONTROL BLOCK LIST HEAD 






fINDEX BIT MAP 1ST LBN HIGH BYTE 






lIMOEX BIT MAP SIZE IN BLOCKS 






fINDEX BITMAP 1ST LBN LOW BITS 






fM.AX NO, OF FILES ON VOLUME 






fDFLT SIZE OF WINDOW IN WO. OF RTRV 


PTRS 


jVALUE IS < 128, 






fSTORAGE BIT MAP CLUSTER FACTOR 






fSTORAGE BIT HAP SIZE IN BLOCKS 






fSTORAGE BIT MAP 1ST LBN HIGH BYTE 




fDEFAULT FILE EXTEND SIZE 






fSTORAGE BIT map 1ST LBN LON BITS 






fVOLU^E COVER'S UIC 






fVOLU*F PROTECTION 






fVOLUME CHARACTERISTICS 






fVOLUME DEFAULT FILE PROTECTION 






fVOLUME FILE SEQUENCE NU M BER 






fNUMBER OF FREE BLOCKS ON VOLUME 


HIGH BYTE 


fCOUN'T OF AVAILABLE LRU SLOTS IN 


FCB 


LIST 


fNUMBER OF FREE BLOCKS ON VOLUME 


LOW 


BITS 


fSIZE IN BYTES OF VCB 







I 

f FILE COM»OL BLOCK 
> 

.ASECT 
,r«? 

F.LINKj ,BLKW 
F.FNUMl ,BLKw 
F.FSEQl ,BLKw 

.SLKw 
F.FOWN: ,BLKw 
F.FPROf ,BLK-t 
F.UCHAj ,8LKB 
F.SCHAi .BLKB 
F.HDLBl ,BLKW 

F.LBNi ,8LKw 



F.SIZE: 
F.NACS! 
F.NLCKj 

F.STATJ 



F.DREFi 
F.DRNM. 

F.LGTH, 



,BLKw 2 
.BLKB 1 
.BLKB 1 
S.STBK=.-F,LBN 
.BLKw l 
FC i *AC»ie'3ia00 
FC,DIR=a000? 
FC.CEFb2E0R(5 
FC.FCCsl&0e3 
,8LK'* 1 
,BLKw 1 
,BLKW 1 



fFCB 


CHAIN POINTER 


fFILE 


NUMBER 


fFILE 


SEQUENCE NUMBER 


fUNUSEO 


fFILE 


OWNER'S UIC 


fFILE 


PROTECTION CODE 


fUSER 


CONTROLLED CHARACTERISTICS 


fSYSTEM CONTROLLED CHARACTERISTICS 


fFILE 


HEADER LOGICAL BLOCK NUMBER 


fBEGINNING OF STATISTICS BLOCK 


fLBN 


OF VIRTUAL BLOCK 1 IF CONTIGUOUS 


f3 IF 


NO* CONTIGUOUS 


fSIZE 


OF FILE IN BLOCKS 


fNO, 


OF ACCESSES 


fNO. 


OF LOCKS 


fSIZE 


OF STATICS BLOCK 


fSTATUS BITS FOR FCB CONSISTING OF 


fSET 


IF FILE ACCESSED FOR WRITE 


fSET 


IF FCB IS IN DIRECTORY LRU 


fSET 


IF DIRECTORY EOF NEEDS UPDATING 


fSET 


IF TRYING TO FORCE DIRECTORY CONTIG 


fDIRECTORY EOF BLOCK NUMBER 


flST 


WORD OF DIRECTORY NAME 


fUNUSED 


fSIZE 


IN BYTES OF FCB 
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SYSTEM DATA STRUCTURES AND SYMBOLIC DEFINITIONS 



1 

| WINDOW 

I 

.ASECT 

W.CTLl .BLKW 1 

Wl.RDVs429 
KI B «NRVaieaP 

wi.EXT«2eae 

wI,OLKal?)00?! 

Wl,BPSsl0800G 
W.VBNi ,8LKB 1 
W.WISZi .BLKB 1 

.8LKW 1 
W.FCBl .BLKW 1 
n a R T R V i 



lL0-*i 


3YTE a 


(HIGH 


BYTE 


(READ 


VIRTU 


»WRITE VIRT 


(EXTEND ALL 


(SET 


IF LOC 


f SET 


IF DEA 


(BYPASS ACC 


fHIGH 


BYTE 


(SIZE 


IN RT 


fLOW 


ORDER 


(PILE 


CONTR 


. ncfect rn 

fwi 1 4L 1 ■ w 



* OF WAP ENTRIES ACTIVE 
CONSISTS OF THE FOLLOWING BITS 
AL BLOCK ALLOWED IF SET 
UAL SLOCK ALLOWED IF SET 
OWED IF SET 

KED AGAINST SHARED ACCESS 
CCESS LOCK ENABLED 
ESS INTERLOCK IF SET 
OF 1ST VBN MAPPED BY WINDOW 
RV PTRS OF WINDOW (7 BITS) 
WORD OF 1ST VBN MAPPED 
OL BLOC* ADDRESS 

n itT DCTSTfUAl O ft T M T F D TKi ui T M ft ft W 



.PSECT 

.MACRO FUDFS 

,END M FUDFS 

.END* FUDFS 

.MACRO HDRDF$,L#B 



!♦ 



TASK HEADER OFFSET DEFINITIONS 



.=0 

H.CSPi 

H.HDLN 

H.PCBT 

H.PCBC 

H.DSWj 
H.FCSl 
H.FORT 
H.OVLY 
H » R S v D 
H.EFL* 
H.CUIC 
H.DUIC 
H.IP3I 
H.IPCl 
H.ISPi 
H.ODVA 
H.ODVL 
H.TKVA 
H.TKVL 
H.PFVA 
H.FPVA 
H.RCVA 



.ASECT 



'L' 

i'L 

I'L 
I'L 

'L' 

» I 9 

<m 

i'L 
t'L 
I'L 
i'L 
i'L 
I'L 
'L' 
'L' 
'L' 



t'L 
I'L 
:'L 
I'L 
i'L 
I'L 
I'L 



H.FPSAi'L 



H.GARD 
H.NLUN 
H.LUNj 



I'L 

I'L 
'L' 



,PS 



LKW 

BLKW 

BLKW a 

BLKW 3*4 

K* 

LKW 

LKW 

BLKW 

BLKW 

3 L K W 

8LKW 

BLKW 

BLKW 

LKw 

LKw 

LKw 

SLKW 

BLKW 

BLKw 

BLKfc 

BLKW 

BL<w 

BLKW 

BLKW 

KW 

BLKW 

BLKW 

LKW 

ECT 



(CURRENT 


STACK POINTER 




IHEADER LENGTH IN BYTES 




(TASK PARTITION DESCRIPTOR 




(COMMON PARTITION DESCRIPTORS 




(BOUNDRY 


WORD FOR PCB ADDRESSES 


> (ALWAYS=0) 


(TASK DIRECTIVE STATUS WORD 




• ere t MSi 


RE POINTER 




(FORTRAN 


IMPURE POINTER 




(OVERLAY 


IMPURE POINTER 




(KtaCKVCL 


KUi'MJC* LULAllUiN 




(EVENT FLAG MASK wORDS 




(CURRENT 


TASK UIC 




(DEFAULT 


TASK UIC 




(INITIAL 


PROCESSOR STATUS WORD 


CPS) 


(INITIAL 


PROGRAM COUNTER (PC) 




(INITIAL 


STACK POINTER (SP) 




(ODT SST 


VECTOR ADDRESS 




(ODT SST 


VECTOR LENGTH 




(TASK SST 


VECTOR ADDRESS 




(TASK SST 


VECTOR LENGTH 




(POWER FAIL AST CONTROL BLOCK ADDRESS 


(FLOATING 


POINT AST CONTROL BLOCK ADDRESS 


(RECIEVE 


AST CONTROL BLOCK ADDRESS 


(RESERVEC 


WORD 




(POINTER 


TO FLOATING POINT/EAE 


SAVE AREA 


(RESERVEC 


WORD 




(POINTER 


TO HEADER GUARD WORD 




(NUMBER OF LUN'S 




(START OF 


LOGICAL UNIT TABLE 





.MACRO 

.END* 
.ENDr' 



HDRDFS 
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.MACRO HWDDF$,L,B 



> + 

» HARDWARE REGISTER ADDRESSES AND STATUS CODES 

f- 



MPCSRs'8'1777a6 

MPARs'B'172100 

PIRQs'B'177772 

PR0s»B'i? 

PR is '8* as? 

PR4b'3'207 

PR5b'B'244 

PR6x'B'3P« 

PP7s'8'34* 

PSs'8'177776 

SWRb'S'17757? 

TPSs'B'l7756u 



ADDRESS CF PDP-11/7? MEMORY PARITY REGISTER 

ADDRESS OF FIRST *£MORY PARITY REGISTER 

PROGRAMMED INTERRUPT REQUEST REGISTER 

PROCESSOR PRIORITY 

PROCESSOR PRIORITY 1 

PROCESSOR PRIORITY a 

PROCESSOR PRIORITY 5 

PROCESSOR PRIORITY 6 

PROCESSOR PRIORITY 7 

PROCESSOR STATUS WORD 

CONSOLE SWITCH AND DISPLAY REGISTER 

CONSOLE TERMINAL PRINTER STATUS REGISTER 



1 + 

I EXTENDED ARITHMETIC ELEMENT REGISTERS 



.IF DF E$$EAE 



AC*'BM773£2 

MQ='B'1773^4 
SCb*BM77318> 



f ACCUMULATOR 
|MULTIPLIER-OUOTIENT 
fSHlFT COUNT 



,ENDC 



I MEMORY MANAGEMENT HARDWARE REGISTERS AND STATUS CODES 



,IF DF m$$mge 



KDSAR^s 
KDSDRgs 
K I S A R t? = 
KISARbs 
KISAR7B 
KISDR?s 
KISDP6= 
KISDR7= 
SISDRtfs 
UDSAR0B 
UDSDR?= 
UISARSs 
UISARas 

UISARSs 
UISARfes 

UISAR7= 
UISDR^s 
UISDRaa 
UISDOSs 
UISDR6= 
UISDR7s 



'B' 

'6' 
'B' 
'B' 
'3' 

'R* 

'3' 

*ft ' 

*B' 
'E' 
'B' 
'?.' 
# R* 
'?■' 

'8 ' 
# a * 

'B* 
'8' 

'P* 

'B' 



172360 
172320 
172340 
172354 
172356 
1723?? 
172314 
172316 
17223P 
177660 
177620 
17764? 
17765? 
177652 
17765a 
177656 
1 7 7 6 % 's 
!77blS 
177612 
17761a 
177*16 



fKERNEL 


D PAR 





fKERNEL 


D PDR 





fKERNEL 


I PAR 


ft 


fKERNEL 


I PAR 


6 


fKERNEL 


I PAR 


7 


fKERNEL 


I PDR 


1? 


fKERNEL 


I PDR 


6 


fKERNEL 


I PAR 


7 


^SUPERVISOR 


I 


PDR 


lUSER 


D 


PAP 


Pi 




fUSER 


D 


PDR 


2 




fUSER 


I 


PAR 


PI 




fUSER 


I 


PAR 


4 




lUSER 


I 


PAR 


5 




|US£o 


I 


PAR 


6 




lUSER 


I 


PAR 


7 




fUSER 


I 


PDR 







fUSER 


I 


PDR 


u 




fUSER 


I 


PDR 


5 




fUSER 


I 


PDR 


6 




fUSER 


T 
i. 


PDR 


7 
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UBMPRs'3M70280 

CMODE»'B'l<l0i(?00 

PMQDE*'B'3!2 r 3?g!- 

SR0s'B'177572 

SP3s'6 # l725l6 



lUNIBUS CAPPING REGISTER 
jCURRENT MODE FIELD OF PS WORD 
jPREVIQUS MQDE FIELD OF PS WORD 
jSEGMENT STATUS REGISTER w 
ISEGMENT STATUS REGISTER 3 



,EnDC 



I FEATURE SYMBOL DEFINITIONS 



H«DDF$ 



. I IF NDF S$$YDF , .LIST 



FE, 
FE 


,EXT = 

,MUP = 


'P'l 
'B'2 

,*ACRO 
, E N D M 
.EMDf^ 



Ml/70 EXTENDED MEMORY SUPPORT 
fMULTI-USER PROTECTION SUPPORT 



.MACRO LCBDF$,L#B 
LOGICAL ASSIGNMENT CONTROL BLOCK 

THE LOGICAL ASSIGNMENT CONTROL BLOCK CLCB) IS USED TO ASSOCIATE A 
LOGICAL NAME WITH A PHYSICAL DEVICE UNIT. LCB'S ARE LINKED TOGETHER 
TO FORM THE LOGICAL ASSIGNMENTS OF A SYSTEM, ASSIGNMENTS MAY BE ON 



.ASECT 

,S0 

l.lnk:'l' .blkw i 

L.NAMf'L' .BLKwi 1 
L.UNITt'L' .BLKB i 
L.TYPEl'L* .BLKB \ 
L.UCBl'L' .BLKW 1 
L.ASGj'L' . a L k w 1 
L.LGTHs'B'.-L.LNK 
.PSECT 



.maCPO 
,E*DM 

,ENDM 



LCBDF$,X,Y 



ILINK TO NEXT LCB 

fLOGICAL NAME OF DEVICE 

fLOGICAL UNIT NUMBER 

tTYPE OF ENTRY C0»SYSTEM WIDE) 

I TI UCB ADDRESS 

tASSlGNMENT UCB ADDRESS 

jLENGTH CF LCB 
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.MACRO PCBDFS 

I PARTITION CONTROL BLOCK OFFSET DEFINITIONS 
f- 



,B0 

P.LNKI 

P,NAM| 

P.SUBl 

P.MAINt 

P.RELl 

P.SIZEi 

P f BLKSl 

P. HAITI 

P.SWSZl 

P.8USYI 

P.TCBi 

P,NAPR| 

P.STATl 



.ASECT 

• BLKi^ 

.BLKW 
.BLK.W 
.BLKW 
.BLKW 
,BLK* 

.BLKW 
.BLKW 
.SLKB 
.BLKW 
.BLKB 
,8LKB 



f LINK TO NEXT PARTITION PCB 

fPARTITION NAME IN RAD50 

fPOINTER TO NEXT SUBPARTITION 

fPOINTER TO MAIN PARTITION 

fSTARTlNG PHYSICAL ADDRESS OF PARTITION 

fSIZE OF PARTITION IN BYTES 

f SIZE OF PARTITION IN 32* BLOCKS (SYSTEM ONLY) 

iPARTITION WAIT QUEUE LISTHEAD (2 WORDS) 

fPARTITION S^AP SIZE (SYSTEM ONLY) 

fPARTITION BUSY FLAGS 

fTCB ADDRESS OF OWNER TASK 

fNUMBER OF APR'S TO LOAD 

fPARTITION STATUS FLAGS 



.IF DF M$$MGE 



P.PDRi .BLKW 
P.HDRf .BLKW 

.IFF 

P,HDR*P.R£L 

.ENDC 



ICONTENTS OF LAST PDR TO BE LOADED 
fPOINTER TO HEADER CONTROL BLOCK 



fPOINTER TO HEADER CONTROL BLOCK 



P.LGTHa, 



.PSECT 



iLENGTH OF PARTITION CONTROL BLOCK 



f + 

f PARTITION STATUS BYTE BIT DEFINITIONS 
f 



PS, 


,C0Mb22(7. 


PS, 


,PICsl»«8 


PS, 


SYSc4* 


PS, 


DRV=2* 


PS, 


APRb7 




•.MACRO 




.ENDM 




,ENDM 



fLIBRARY OR COMMON BLOCK (lsYES) 

fPOSITION INDEPENDENT LIBRARY OR CO^O* Cl=YEfi) 

fSYSTEM CONTROLLED PARTITION (i«YES) 

fDRIVER IS LOADED IN PARTITION C1=YES) 

^STARTING APR NUMBER MASK 



PCBDFS 
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.MACRO PKTDFS,L#B 



1 + 



leunrijorn nut 



SYSTE 



tcm toad r n m t o r. i ai nri^ necsFT nFcTMTTfiNS 



.ASECT 

,^L«" 
A.CBU'L' ,HLKW 
A.BYTl'L' .3L«* 
A.ASTi'L' .SLK* 
A.NPRi'L' .PLKW 
A.PR*t'L' ,3L** 



f AST QUEUE THREAD *QRD 

ILEVGTH OF CONTROL BLOCK IN BYTES 

|NU*3E» CF BYTES TO ALLOCATE ON TASK STACK 

fAST TRAP ADDRESS 

jNU^BER CF AST PARAMETERS 

»FIRST AST PARAMETER 



1 I/O 
I- 



PAC^tT lFFSfc.1 UtFl v i I iL ,r NS 



.ASECT 



,3(3 

I.lNKl'L 

I.PRIl'L 

I.EF^i'L 

I.TCBl'l 

I.LN2^L 

I , U C 8 i * L 

I . F C N ! ' L 

I.I0S3:' 



' .3 
L' . 
."LX 
.BL* 



LK* 
L<B 
L«S 
L*^ 
LKI« 

I V ... 

PLK- 



I.ASTl'L 

T s PRMj 'L 

I.LGTHs' 



ILK' 
:LK- 



,«L< 
.PSE 



Il/C QUEUE THREAD *0RD 

fREGUEST PRIORITY 

fEVENT FLAG NUMBER 

iTCB ADDRESS OF REQUESTOR 

jPCI^TER TO SECOND LU* wO*D 

f I/O FUNCTION CODE 

^VIRTUAL ADDRESS OF I/O STATUS BLOC 
I I/O STATUS BLOCK RELOCATON BIAS 
f I/O STATUS BLOC* ADDRESS 
tAST SERVICE ROUTINE ADDRESS 
iRESERVED FOR MAPPING PARAMETER #1 
^PARAMETERS 1 TO 6 
jLEfcGTH OF I/O REQUEST CONTROL BLOCK 



CT 



,EN0 M 
.E^Ov. 



PKTDFS 
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,*ACR0 SCB0FJ,L,8 



rUS CONTROL BLOCK 

STATUS CONTROL BLOCK (SCB) DEFINES THE STATUS OF A DEVICE CONTROLLER. 
?E IS ONE SCB FOR EACH CONTROLLER IN A SYSTE*. THE SCB IS POINTED TO 
JNIT CONTROL BLOCKS, TO EXPAND ON THE TELETYPE EXAMPLE ABOVE, EACH TELE- 
■ INTERFACED VIA A DLli-A *OuLD HAVE A SCB Sl^CE EACH DL11-A IS 4^ IN. 

:ndent interface unit, the teletypes interfaced via the ohu *o<iLn also 

< HAVE AN SCB Sl^CE THE OHH Is A SINGLE CONTROLLER BUT MULTIPLEXES *A^V 
rs IN PARALLEL, 



.ASECT 
'72 

ri'L' 

I'L' 

I'L' 

I'L' 

*L' 

'L' 



.BLK6 1 
,BLK6 1 
,BLKw i 
.BLKu j 
,BLK* 2 
.BLKP 1 



'L' 
'L' 
'L' 
'L' 
'L' 
'L' 
'L' 



'L' 



,BLKB 
,6LK6 
.BLK3 
.&L»<6 
.BLK'a 
,9LKw 
,BL** 

LK* 

LK> 

L K fc 

.PLKw 

LK. 

,BL** 



jNUMBE 


fOFFSE 


jSAVEO 


IDEVIC 


iCONTR 


fDEVIC 


1 INTER 


fCURRE 


f I w I T I 


fCOMTR 


fCONTR 


1 ADORE 


lADDRE 


jFORK/ 


jFORK- 


f FORK- 


fFOPK- 


jFCR«« 


fFCRK- 


lli/7? 



R OF REGISTERS TO COPY 0* ERROR 
T TO FIRST DEVICE REGISTER 

I/O ACTIVE BIT M AP AND POINTER TO EMB 
E I/O ACTIVE BIT "ASK 
OLLER I/O QUEUE LISTHEAD 
E PRIORITY 

RUPT VECTOR AOnRtSS /a 
M TIMEOUT COUNT 
AL TI M EGUT COl^T 
OLLER INDEX 

OLLEP STATUS C ? =IDLE, lsBUSY) 
SS OF CCNTPCL STATUS REGISTER 
SS OF CURRENT I/O PACKET 
TI^E REQUEST BLOC* LI f v< -Q&D 
PC/TI M E-CUEUE REQUEST TYPE 
R5/TI*E-REGUEST IDENTIFICATION 
R4|/TI M E-L0^ ORDER TI'E 

U-MUSEO/TIME-HIGH ORDER TI*E/CHANNEL CONTROL BLOCK 
UNUSED/TI^E-SuBRCUTIf-'E ADDRESS 

EXTENDED *E*CRY UNIBuS DEVICE C-9LCCK 



.PSECT 



'US CONTROL BLOCK PRIORITY BYTE CONDITIO* CODE STATUS BIT DEFINITIONS 



s * P ■ * 1 
s ' Q ' 2 

S ' P * L 
1 7 



fERROc? IN PROGRESS (lsYES) 

jERRCR LCGGING ENABLED (^=YES) 

fERROR LOGGING AVAILABLE (1=VES) 

fSPARE BIT 



, * A C p D 

.ENC 

,E^D" 



vSCBOF$,x # Y 
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.MACRO TCBDFS,L,B 



»♦ 



| TASK 


Cj^TSOt BLOCK OFFSET 


1 

I TASK 

I" 


CONTROL BLOCK 




.ASECT 


• ■* 




T.LNKj' 


'L* .BLKW 1 


T.PRIi' 


'L' .3LKS 1 


T.IOCl' 


'L' .9LKB 1 


T.TCBj' 


•L' ,8LK* 1 


T.NAM!' 


'L' .BLK* 2 


T.RCVL 


'L* .BLKW 2 


T.ASTL 


'L' ,BLKw 2 


T.EFLG 


l'L' .BLKW 2 


T.UCBi' 


'L' .3LKW l 


T.TCBL 


I'L' .BLKw 1 


T.STAT 


l*L' .BLKB 3 


T.LBN:- 


P L' .BLKB 3 


T.LDVi' 


'L' .BLK* 1 


T.PCBi 


'L' ,3LKW 1 


T.MXSZ 


j'L' .BLKW 1 


T.ACTL 


t'L' ,3LKw 1 


T.LGTH: 


:'3'. 


T.EXTs 


'8*. -T.LGTH 




.PSECT 



». !N 1/ 5ISIU5 Ufl^lllU^J 



fUTlLlTY LINK WORD 

jTASK PRIORITY 

f I/O PENDING CQU^T 

fPOINTER TO T.LNK OF TCB ITSELF 

jTASK NA^E IN RAC58 

RECEIVE QUEUE LISTHEAD 

I AST QUEUE LISTHEAD 

iTASK LOCAL EVENT FLAGS 1-32 

fUCB ADDRESS FOR PSEUOO DEVICE 'TI' 

fTASK LIST THREAD WORD 

>TASK STATUS *ORD AND EXTENSION BYTE 

tLBN OF TASK LOAD IMAGE 

fUCB ADDRESS OF LOAD DEVICE 

|PCB ADDRESS OF TASK PARTITION 

jMAXlMUM SIZE OF TASK IMAGE (MAPPED ONLY) 

lADDRESS OF NEXT TASK IN ACTIVE LIST 

jLENGTH OF TASK CONTROL BLOCK 

jLENGTH OF TCB EXTENSION 



J + 

I TASK STATUS DEFINITIONS 



j TASK STATUS wORD 
J- 



TS. EXE = ' 


' B * 1 ? '3 


TS.RD^*' 


»B'a?c;00 


TS.DSTs- 


' B * 2 $ £ 


TS.MSS*' 


'8'14000 


TS.PMDs' 


'%'azm 


TS.STPs 


'B'23?0 


TS,RE*= 


'B'HM 


TS.ACP*' 


'B'a#2 


TS.ASTr 


'8 # 2i?? 


TS.CHKs 


'S' \ : A% 


TS.BFXs 


'S'4^ 


TS.FXDs 


*B'2tf 


TS.OUTs 


'8'H 


TS.CKPs 


'8'4 


TS.CKRs 


'3'2 


TS.CKOs 


'6-1 



jTASK IS IN EXECUTION Cls'B'YES) 
I I/O RUN DOWN IN PROGRESS Cls'B'YES) 
tAST RECOGNITION DISABLED Cls'B'YES) 
fABORT MESSAGE BEING OUTPUT Cls'B'YES) 
fDUMP TASK ON SYNCHRONOUS ABORT CBsYES) 
jTASK STOPPED FOR TERMINAL INPUT ClsYES) 
fREMOVE TASK ON EXIT Cls'B'YES) 
jANCILL,ARY CONTROL PROCESSOR (ls'B'YES) 
»AST I* 1 PROGRESS Cls'B'YES) 
fTASK IS CHECKPOINTABLE Cls'B'YES) 
iTASK BEING FIXED IN MEMORY (ls'B'YES) 
jTASK FIXED IN memqsy Cls'B'YES) 
fTASK IS OUT OF MEMORY Cls'B'YES) 
fTASK IS CHECKPOINTED Cls'B'YES) 
fCHECKPOINT REQUESTED Cls'B'YES) 
iCHECKPOINT DISABLED (ls'B'YES) 



1 + 

j TASK BLOCKING STATUS MASK 

I- 

TS,3LKs'B'TS.CKPlTS,CKRlTS,EXEtTS,MSGlTS.CUTiTS,RDNlTS.STP | 

I TASK STATUS BYTE EXTENSION 
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S.HLTs'B'200 

S.PRVs'B'W 

S,ABO*'B*flvS 

S,HCR='8'22! 

S t SPNs'BM0 

S.SP*a'B'U 

S.WFR«*B # 2 

S.WFRa'B'l 

.MACRO 
,ENQM 

,EN0w 



TCBDF$ 



jTASK IS BEING HALTED Clc'B'YES) 

|TASK IS PRIVILEGED (1='8*YES) 

fTASK MARKED FOR A30»T (ls'B'YES) 

jTASK REQUESTED AS EXTERNAL M CR FUNCTION (la'B'YES) 

fSAVED TS.SPN On AST IN PROGRESS 

iTASK SUSPENDED (1='B'YES5 

fSAVED TS. WFR ON AST I* PROGRESS 

|TA8K IN WAITFOR STATE (1='B'YES) 



.MACRO UCBDF$,L|B 



UNIT CONTROL BLOCK 




BOVE, 



I.DCBl 
I, RED* 
I.CTL: 
I.STSl 
I. UNIT 
I.ST2I 
I.CWH 
I.CW2I 
I.CW3I 
J.cwui 
J.SCBi 
J.ATTl 
I.BUFi 

I.CNTl 
J.ACPs 
J.VCBs 
J.CBFa 
J,UIC= 



.ASECT 

L' .BLK^ 
L' .BLKw 
'L' .BLKB 
L' .BLKB 
'L' ,BLK8 1 
L' ,BL<8 

,3LKW 

.BLKW 

,8LKW 

.3LKW 

.BLKW 

,BLK* 

,8LKW 
,BLK* 
'L' .BLKW 
B'U.CNT+2 
B'U.C^T+a 
, 8'U.CNT+2 
B'U.CNT+<9.*2> 
.PSECT 



L' 
L' 
L' 

L' 
L' 
L* 
L* 



iBACK POINTER TO DCS 

IPOINTEP TO REDIRECT UNIT UCB 

,-CONTRCL PROCESSING FLAGS 

|UNIT STATUS 

fPHYSICAL UNIT NUMBER 

|UNIT STATUS EXTENSION 

>FIRST DEVICE CHARACTERISTICS NORD 

tSECOND DEVICE CHARACTERISTICS WORD 

iTHIRD DEVICE CHARACTERISTICS *ORD 

fFOURTH DEVICE CHARACTERISTICS WORD 

^POINTER TO SCB 

|TCB ADDRESS OF ATTACHED TASK 

^RELOCATION; BIAS OF CURRENT I/O REQUEST 

jBUFFER ADDRESS OF CURRENT I/O REQUEST 

fBYTE COUNT OF CURRENT I/O REQUEST 

jADDRESS OF TCB OF MOUNTED ACP 

^ADDRESS OF VOLUME CONTROL BLOCK 

^CONTROL BUFFER RELOCATION AND ADDRESS 

^TERMINAL UIC (TERMINALS ONLY) 



DEVICE TABLF STATUS DEFINITIONS 

DEVICE CHARACTERISTICS word t CU.CW1) DEVICE TYPE DEFINITION BITS, 
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DV.RECs'B'l fRECORD ORIENTED DEVICE Cl-YES) 

DV.CCLs'3'2 ^CARRIAGE CONTROL DEVICE ClsYES) 

DV.TTYs'B'u ^TERMINAL DEVICE (1«YES) 

DV«DIR3" , K' r iiS priut oi^uliupcu i/tuwu u B ito< 

DV.SDIs'B'20 fSINGLE DIRECTORY DEVICE C1«YES) 

DV.SQDs'B'40 ^SEQUENTIAL DEVICE ClsYES) 

DV,8WLs'B'4000 ?UNIT SOFTWARE WRITE LOCKED C1«YES) 

DV,PSE« # BM«000 fPSEUDO DEVICE (1*YES) 

DV.COMs'B'23000 fDEVICE IS MOUNTABLE AS COM CHANNEL ClsYES) 

DV,Fils'8'40000 fDEVICE IS MOUNTABLE AS Fil DEVICE C1*YES) 

DV,MNTs*BM00000 fDEVICE IS MOUNTABLE ClsYES) 

f + 

I TERMINAL DEPENDENT CHARACTERISTICS WORD 2 CU,CN2) BIT DEFINITIONS 

f" 

U2,DHls*BM00000 fUNlT IS A DHU/DJii ClsYES) 

U2.DJi«'B'«?000 f UNIT IS A DJll ClsYES) 

U2,RMTs'3'20000 |UNIT IS REMOTE ClsYES) 

U2,LOGs'B'400 fUSER LOGGED ON TERMINAL ClsYES) 

U2,LWCa # B'200 fLOWER CASE TO UPPER CASE CONVERSION ClsYES 

U2,OFFs'B'lS0 fOUTPUT IS TURNED OFF ClsYES) 

U2,PND='B»40 lOUTPUT BYTE PENDING (1«YES) 

U2.AT.='8'20 >MCR COWHAND AT, BEING PROCESSED ClsYES) 

U2,PRVs'B'12 fUNIT IS A PRIVILEGED TERMINAL ClsYES) 

U2,L3Ss'B*A fUNIT IS A LA30S TERMINAL ClsYES) 

U2iVT5SfB*2 f V N A I A 5 A YIB3D IC.T~lNAu l 1 S i t. s> i 

U2,SLV8*B*i fUNIT IS A SLAVE TERMINAL ClsYES) 

| + 

I RH11-RS03/RS04 CHARACTERISTICS WORD 2 CU.CW2) BIT DEFINITIONS 

>- 

U2,R04*'9'100000 > UNIT IS A RS04 ClsYES) 

I* 

f RH11-TU16 CHARACTERISTICS WORD 2 CU.CW2) BIT DEFINITIONS 

f- 

U2,7CHs'B*12000 »UNIT IS A 7 CHANNEL DRIVE ClsYES) 

r+ 

> UNIT CONTROL PROCESSING FLAG DEFINITIONS 
!• 

UC,ALGs'B»230 fBYTE ALIGNMENT ALLOWED ClsNO) 

UC,NPRs'BM00 fDEVICE IS AN NPR DEVICE ClsYES) 

UC.GUEs'B'40 fCALL DRIVER BEFORE QUEUING ClsYES) 

UC.PWFs'B'23 fCALL DRIVER AT PQ*ERFAIL ALWAYS ClsYES) 

UC.ATTs'B'l*' fCALL DRIVER ON ATTACH/DETACH ClsYES) 

UC.KILs'S'a fCALL DRIVER AT I/O KILL ALWAYS ClsYES) 

UC.LGHs'8'3 fTRANSFER LENGTH MASK BITS 

>♦ 

l UNIT STATUS BIT DEFINTIONS 

f 
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US,9SYs'M'2?0 iUNIT IS BUSY C1«YES) 

US.NNTa'9 # 15J0 fUNIT IS MOUNTED (0«'B'YES) 

US.FORs'B'utf fUMT IS COUNTED AS FOREIGN VOLUME ClaYES) 

US.M0MB*g»23 jUNIT IS MARKED FOR DISMOUNT ClaYES) 

J + 

I UNIT STATUS EXTENSION BIT DEFINITIONS 

f- 

US.OFLa'B'i iUNIT OFFLINE (1=YES) 

US,PED='6'2 fUNIT REDIPECTABLE (3=YES) 

1 + 

I CARD READER DEPENDENT UNIT STATUS BIT DEFINITIONS 

I- 

US.ABQs'B'l fUNIT IS MARKED FOR ABORT IF NOT READY ClsYES) 

US.MDEs'B'2 fUMT IS IN £29 TRANSLATION NODE (lsYES) 

> + 

f FILES-U DEPENDENT UNIT STATUS BITS 
»- 

US.WCK*'?*^ I^RITE CHECK ENABLED ClsYES) 

1 + 

I TERMINAL DEPENDENT U^IT STATUS BIT DEFINITIONS 
I- 

US.DSBa'BM? fUNIT IS DISABLED ClsYES) 

US.CR^a'B'a fUMT IS WAITING FOR CARRIER ClsYES) 

US.ECHs'B'2 fUNIT HAS ECHO IN PROGRESS ClaYES) 

US.OUTa'B'l f UNIT IS EXPECTING OUTPUT INTERRUPT ClaYES) 

?♦ 

1 LPS11 DEPENDENT UNIT STATUS BIT DEFINITIONS 
I- 

US,FRKs'R»2 tFORK IN PROGRESS ClsYES) 

US.SHPs'B'l (SHAREABLE FUNCTION IN PROGRESS C0s'B'VES) 

.MACRO UCBDF$,X,Y 

£ \! r», K- 

.END* 
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INDEX 



Address doubleword, A-l 



Bootstrapping the new system, 2-8 



Development of the address double- 
word, A-l 
Driver code, 5-5 
Driver debugging, 2-7 
Dump output, panic, 2-19 
$DVMSG, 4-1 



Cancel I/O, 1-4 

Crash output, 2-19 

Create Fork process ($FORK) , 1-11, 

4-3 
Creating the address doubleword, 

A-l 
Creating the data structure, 2-2 
Creating the driver source code, 

2-4 



Data items on the stack, 2-18 
Data structure and driver source , 

5-2 
Data structure, source format 

of the, 2-4 
Data structures, 1-5, 3-1, 5-2 
Data structures and their inter- 
relationships, 1-17 
Data structures, creating, 2-2 
Data structures summary, 1-20 
Data structures (system) , 

symbolic definitions, B-l 
DCB, 1-6, 3-9 
DCB fields, required, 

D.DSP, 2-3, 3-11 

D.LNK, 2-2, 3-10 

D.MSK, 2-3, 3-12 

D.NAM, 2-2, 3-10 

D.UCB, 2-2, 3-10 

D.UCBL, 2-3, 3-10 

D.UNIT, 2-3, 3-10 
Debugging Tool, Executive, 2-9 
Device Control Block (DCB), 1-6, 

3-9 
Device description, 5-1 
Device interrupt, 1-4 
Device interrupt vector, 1-9 
Device message output, 4-1 
Device timeout, 1-4 



Executive Debugging Tool, 2-9 
Executive I/O processing, 1-3 
Executive services, 1-9 
Executive services available to 
I/O drivers, 4-1 



Fault, 

classifications, 2-10 

immediate servicing, 2-11 

internal SST, 2-16 

isolation, 2-10 

non-normal SST, 2-17 

other pertinent isolation data, 
2-12 

tracing, 2-13 
FCS, 1-2 

Flow of an I/O request, 1—14 
$FORK, 1-11,' 4-3 
Fork list, 1-9 

Function codes for I/O, 3-15 
Function masks, 

ACP, 3-13 

control, 3-13 

legal, 3-13 

no-op' ed, 3-13 



Get Byte ($GTBYT) , 4-4 

Get Packet ($GTPKT) , 1-11, 4-5 

Get Word ($GTWRD) , 4-6 

$GTBYT, 4-4 

$GTPKT, 1-11, 4-5 

$GTWRD, 4-6 



Including a user-written driver - 

an example, 5-1 
Incorporating tasks into the 

system, 2-8 
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Incorporating the user-<?written 

driver, 2-1, 2-7 
Interrelation of the I/O Control 

Blocks, 1-7 
Interrupt exit ($INTXT) , 4-8 
Interrupt Save ($INTSV) , 1-11, 

4-7 
$INTSV, 1-11, 4-7 
$INTXT, 4-8 

I/O alternate entry, 4^9 
I/O control blocks, interrelation- 
ship of the, 1-7 
$IOALT, 4-9 
$IODON, 1-11, 4-9 
$IOFIN, 4-10 

I/O Done ($IODON) , 1-11, 4-9 
I/O Driver, role of an, 1-4 
I/O finish, 4-10 
I/O function codes, 3-15 
I/O hierarchy, 1-1 
I/O initiator, 1-4 
I/O Packet, 1-8, 3-2 
I/O Packet fields, 

LAST, 3-6 

I.EFN, 3-4 

I.FCN, 3-5 

I.IOSB, 3-5 

I.LN2, 3-4 

I.LNK, 3-4 

I.PRI, 3-4 

I.PRM, 3-6 

I.TCB, 3-4 

I.UCB, 3-5 
I/O philosophy, 1-1 
I/O processing, Executive, 1-3 
I/O Queue, 1-8 

I/O request, flow of an, 1-14 
I/O system - philosophy and 
structure, 1-1 



Mapped system header, 2-15 
Mask word creation, 3-14 
Masks, function, 3-12 



Panic dump output, 2-19 
Post-driver initiation services, 

1-10 
Power failure, 1-4 
Pre-driver initiation processing, 

1-10 
Processing at priority 7 with 

interrupts locked out, 1-13 
Process-like characteristics of 

a driver, 1-12 



Processing at fork level, 1-14 
Processing at priority of inter- 
rupting source, 1-13 
Programming conventions, 1-12 
Programming protocol, 1-12 
Programming standards, 1-12 
$PTBYT, 4-11 
$PTWRD, 4-12 
Put Byte, 4-11 
Put Word, 4-12 



QIO, 1-3 



Re-assembly, 2-7 

Rebuilding and re-incorporating 

the user driver, 2-7 
Rebuilding the Executive, 2-8 
Register conventions, system 

state, 4-1 
Required Device Control Block 
CDCB) fields, 

D.DSP, 2-3, 3-11 

D.LNK, 2-2, 3-10 

D.MSK, 2-3, 3-12 

D.NAM, 2-2, 3-10 

D.UCB, 2-2, 3-10 

D.UCBL, 2-3, 3-10 

D.UNIT, 2-3, 3-10 
Required Status Control Block 
(SCB) fields, 

S.CON, 2-4, 3-18 

S.CSR, 2-4, 3-18 

S.ITM, 2-4, 3-18 

S.LHD, 2-4, 3-17 

S.PRI, 2-4, 3-17 

S.STS, 2-4, 3-18 

S.VCT, 2-4, 3-17 
Required Unit Control Block (UCB) 
fields, 

U.ATT, 2-3, 3-25 

U.CTL, 2-3, 3-21 

U.CW1, 2-3, 3-23 

U.CW2, 2-3, 3-24 

U.CW3, 2-3, 3-24 

U.CW4, 2-3, 3-24 

U.DCB, 2-3, 3-21 

U.RED, 2-3, 3-21 

U.SCB, 2-3, 3-24 

U.ST2, 2-3, 3-23 

U.STS, 2-3, 3-22 

U.UNIT, 2-3, 3-23 
Role of an I/O driver, 1-4 
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SCB, 1-6, 3-16 

SCB fields other than required, 

S.CTM, 3-18 

S.FRK, 3-19 

S.PKT, 3-19 
SCB fields, required, 

S.CON, 2-4, 3-18 

S.CSR, 2-4, 3-18 

S.ITM, 2-4, 3-18 

S.LHD, 2-4, 3-17 

S.PRI, 2-4, 3-17 

S.STS, 2-4, 3-18 

S.VCT, 2-4, 3-17 
Service calls, 4-1 
Source format of the data struc- 
ture, 2-4 
SST fault, 

internal, 2-16 

non-norma 1 , 2-17 
Stack structure, 

/4-.4--> 4 4-nmn ^<m r» 4- -> s* lr 1_1 O 

uata J. uciuo \jxi oi-av,j\; «. — j_u 

internal SST fault, 2-16 
non-normal SST fault, 2-17 
Status Control Block (SCB), 1-6, 

3-16 
Structure, 1-1 
Symbolic definitions, system 

data structures, B-l 
System data structures symbolic 

definitions, B-l 
System header, 
mapped, 2-14 
unmapped, 2-15 
System-state register conventions, 
4-1 



UCB fields, required (cont.), 
U.ST2, 2-3, 3-23 
U.STS, 2-3, 3-22 
U.UNIT, 2-3, 3-23 
Unit Control Block (UCB), 1-6, 

3-19 
Unmapped system header, 2-14 
Updating the executive object 

module library, 2-7 
User-written drivers, Incor- 
porating, 2-7 



Writing an I/O driver - program- 
ming specifics, 3-1 



XDT, 2-9 



Tasks, incorporating into the 
system, 2-8 



UCB, 1-6, 3-19 

UCB fields other than required, 

U.BUF, 3-25 

U.CNT, 3-26 
UCB fields, required, 

U.ATT, 2-3, 3-25 

U.CTL, 2-3, 3-21 

U.CW1, 2-3, 3-23 

U.CW2, 2-3, 3-24 

U.CW3, 2-3, 3-24 

U.CW4, 2-3, 3-24 

U.DCB, 2-3, 3-21 

U.RED, 2-3, 3-21 

U.SCB, 2-3, 3-24 



Index-3 



RSX-11M Guide to Writing an I/O Driver 
DEC-11-0MWDA-B-D 



READER'S COMMENTS 



NOTE: This form is for document comments only. Problems 
with software should be reported on a Software 
Problem Report (SPR) form 



Did you find errors in this manual? If so, specify by page. 



TO 

C 

_o 

o 

4- 

3 



Did you find this manual understandable, usable, and well-organized? 
Please make suggestions for improvement. 



Is there sufficient documentation on associated system programs 
required for use of the software described in this manual? If not, 
what material is missing and where should it be placed? 



Please indicate the type of user /reader that you most nearly represent. 

| | Assembly language programmer 

| | Higher-level language programmer 

Q Occasional programmer (experienced) 

Q] User with little programming experience 

Q Student programmer 

Q Non-programmer interested in computer concepts and capabilities 



Name — Date 

Organization 

Street 



City - State Zip Code 

or 
Country 

If you require a written reply, please check here. Q 
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